 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual PM4351, PM4354 COMET AND COMET-QUAD DEVICE DRIVER DRIVER MANUAL PROPRIETARY AND CONFIDENTIAL RELEASE ISSUE 2: JUNE, 2001 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual OVERVIEW Scope This document is the user's driver manual for the COMET (PM4351) and COMET-QUAD (PM4354) device driver software. It describes the features and functionality provided by the driver, the software architecture, and the external interfaces of the driver software. Differences in API functionality for COMET and COMET-QUAD devices are listed throughout the API descriptions on a per-function basis. Objectives The main objectives of this document are as follows: * * * Provide a detailed list of the device driver's features Describe the software architecture of the driver (data structures, state diagrams, function descriptions). Describe the external interfaces of the driver. The external interfaces illustrate how the driver interacts with the underlying hardware and RTOS as well as external application software References The main references for this document are as follows: * * PMC-1990315 - Four Channel Combined E1/T1/J1 Transceiver/Framer Data Sheet, Issue 6 PMC-1970624 - Combined E1/T1 Transceiver Standard Product Data Sheet, Issue 10 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 1 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Legal Issues None of the information contained in this document constitutes an express or implied warranty by PMC-Sierra, Inc. as to the sufficiency, fitness or suitability for a particular purpose of any such information or the fitness, or suitability for a particular purpose, merchantability, performance, compatibility with other parts or systems, of any of the products of PMC-Sierra, Inc., or any portion thereof, referred to in this document. PMC-Sierra, Inc. expressly disclaims all representations and warranties of any kind regarding the contents or use of the information, including, but not limited to, express and implied warranties of accuracy, completeness, merchantability, fitness for a particular use, or non-infringement. In no event will PMC-Sierra, Inc. be liable for any direct, indirect, special, incidental or consequential damages, including, but not limited to, lost profits, lost business or lost data resulting from any use of or reliance upon the information, whether or not PMC-Sierra, Inc. has been advised of the possibility of such damage. The information is proprietary and confidential to PMC-Sierra, Inc., and for its customers' internal use. In any event, no part of this document may be reproduced in any form without the express written consent of PMC-Sierra, Inc. (c) 2001 PMC-Sierra, Inc. PMC-2010108 (P1), ref PMC-1991407 (P2) Contacting PMC-Sierra PMC-Sierra, Inc. 105-8555 Baxter Place Burnaby, BC Canada V5A 4V7 Tel: (604) 415-6000 Fax: (604) 415-6200 Document Information: document@pmc-sierra.com Corporate Information: info@pmc-sierra.com Technical Support: apps@pmc-sierra.com Web Site: http://www.pmc-sierra.com Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual TABLE OF CONTENTS Overview...................................................................................................................................................... 1 Table of Contents......................................................................................................................................... 3 List of Figures .............................................................................................................................................. 8 List of Tables................................................................................................................................................ 9 1 2 Introduction ......................................................................................................................................... 12 Software Architecture .......................................................................................................................... 13 2.1 Driver External Interfaces.......................................................................................................... 13 Application Programming Interface .................................................................................... 14 Real-Time Operating System (RTOS) Interface ................................................................. 14 Hardware Interface ............................................................................................................. 14 Main Components ..................................................................................................................... 15 Module Data-Block and Device Data-Blocks...................................................................... 16 Module and Device Management....................................................................................... 17 Interrupt Servicing/Polling................................................................................................... 17 Status and Statistics Collection........................................................................................... 17 Interface Configuration ....................................................................................................... 18 T1/E1 Framers.................................................................................................................... 18 Signal Insertion / Extraction ................................................................................................ 19 Alarm Control and Inband Communications....................................................................... 19 Serial Controller .................................................................................................................. 19 Device Diagnostics ............................................................................................................. 19 Specific Callback Functions ................................................................................................ 20 Software States ......................................................................................................................... 20 Module States ..................................................................................................................... 21 Device States ...................................................................................................................... 22 Processing Flows ...................................................................................................................... 23 Module Management .......................................................................................................... 23 Device Management........................................................................................................... 24 Interrupt Servicing ..................................................................................................................... 25 Calling cometqISR .............................................................................................................. 25 Calling cometqDPR ............................................................................................................ 26 Calling cometqPoll .............................................................................................................. 27 2.2 2.3 2.4 2.5 3 Data Structures ................................................................................................................................... 28 3.1 3.2 Constants .................................................................................................................................. 28 Structures Passed by the Application........................................................................................ 28 Module Initialization Vector: MIV ........................................................................................ 28 Device Initialization Vector: DIV.......................................................................................... 29 3 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual ISR Enable/Disable Mask ................................................................................................... 34 Other API Structures ........................................................................................................... 43 3.3 Structures in the Driver's Allocated Memory ............................................................................. 62 Module Data Block: MDB.................................................................................................... 62 Device Data Block: DDB..................................................................................................... 63 Structures Passed through RTOS Buffers ................................................................................ 65 Interrupt Service Vector: ISV .............................................................................................. 65 Deferred Processing Vector: DPV ...................................................................................... 66 Global Variable .......................................................................................................................... 69 3.4 3.5 4 Application Programming Interface..................................................................................................... 70 4.1 Module Management ................................................................................................................ 70 Opening the Driver Module: cometqModuleOpen .............................................................. 70 Closing the Driver Module: cometqModuleClose ............................................................... 70 Starting the Driver Module: cometqModuleStart ................................................................. 71 Stopping the Driver Module: cometqModuleStop ............................................................... 71 Profile Management .................................................................................................................. 72 Adding an Initialization Profile: cometqAddInitProfile ......................................................... 72 Getting an Initialization Profile: cometqGetInitProfile ......................................................... 72 Deleting an Initialization Profile: cometqDeleteInitProfile ................................................... 73 Device Management ................................................................................................................. 73 Adding a Device: cometqAdd ............................................................................................. 73 Deleting a Device: cometqDelete ....................................................................................... 74 Initializing a Device: cometqInit .......................................................................................... 74 Resetting a Device: cometqReset ...................................................................................... 75 Updating the Configuration of a Device: cometqUpdate .................................................... 75 Activating a Device: cometqActivate .................................................................................. 76 Deactivating a Device: cometqDeActivate.......................................................................... 76 Device Read and Write ............................................................................................................. 77 Reading from Device Registers: cometqRead ................................................................... 77 Writing to Device Registers: cometqWrite .......................................................................... 77 Reading from a block of Device Registers: cometqReadBlock .......................................... 78 Writing to a Block of Device Registers: cometqWriteBlock ................................................ 79 Reading from Framer Device Registers: cometqReadFr ................................................... 79 Writing to Framer Device Registers: cometqWriteFr .......................................................... 80 Reading from Device Indirect Registers: cometqReadFrInd .............................................. 81 Writing to Device Indirect Registers: cometqWriteFrInd..................................................... 81 Reading from Device RLPS Indirect Registers: cometqReadRLPS .................................. 82 Writing to Device RLPS Indirect Registers: cometqWriteRLPS ......................................... 83 Interface Configuration.............................................................................................................. 83 Transmit line coding configuration: cometqLineTxEncodeCfg ........................................... 83 Receive line coding configuration: cometqLineRxEncodeCfg............................................ 84 Analog transmitter configuration: cometqLineTxAnalogCfg ............................................... 85 Analog receiver configuration: cometqLineRxAnalogCfg ................................................... 85 Transmit jitter attenuator configuration: cometqLineTxJatCfg............................................ 86 Receive jitter attenuator configuration: cometqLineRxJatCfg ............................................ 86 4 4.2 4.3 4.4 4.5 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Clock service unit configuration: cometqLineClkSvcCfg .................................................... 87 Receive clock and data recovery options: cometqLineRxClkCfg....................................... 87 Backplane transmit interface configuration: cometqBTIFAccessCfg.................................. 88 Backplane transmit interface configuration: cometqBTIFFrmCfg....................................... 88 Backplane receive interface configuration: cometqBRIFAccessCfg .................................. 89 Backplane receive interface configuration: cometqBRIFFrmCfg ....................................... 89 Receive and transmit HMVIP interfaces configuration: cometqHMVIPCfg ........................ 90 Receive elastic store configuration: cometqRxElstStCfg.................................................... 90 Transmit elastic store configuration: cometqTxElstStCfg ................................................... 90 4.6 T1 /E1 Framers ......................................................................................................................... 91 Set Device Operational Mode: cometqSetOperatingMode ................................................ 91 T1 transmit framer configuration: cometqT1TxFramerCfg ................................................. 92 T1 receive framer configuration: cometqT1RxFramerCfg .................................................. 93 E1 transmit framer configuration: cometqE1TxFramerCfg................................................. 93 E1 receive framer configuration: cometqE1RxFramerCfg.................................................. 94 E1 transmit framer extra bits insertion: cometqE1TxSetExtraBits...................................... 94 E1 transmit framer international bits configuration: cometqE1TxSetIntBits ....................... 95 E1 transmit framer national bits configuration: cometqE1TxSetNatBits............................. 95 E1 receive framer extra bit extraction: cometqE1RxGetExtraBits...................................... 96 E1 receive framer international bit extraction: cometqE1RxGetIntBits .............................. 97 E1 receive framer national bit extraction: cometqE1RxGetNatBitsNFAS .......................... 97 E1 receive framer national bit extraction: cometqE1RxGetNatBitsSMFRM....................... 98 Signal Insertion/Extraction ........................................................................................................ 99 Change of signaling state detection: cometqExtractCOSS ................................................ 99 Signaling state extraction: cometqSigExtract ..................................................................... 99 Signal trunken: cometqSigTslotTrnkDataCfg.................................................................... 100 Alarm and Inband Communications ........................................................................................ 101 Automatic alarm response configuration: cometqAutoAlarmCfg...................................... 101 Alarm insertion: cometqInsertAlarm ................................................................................. 102 HDLC configuration: cometqHDLCEnable ....................................................................... 103 HDLC configuration: cometqHDLCRxCfg......................................................................... 103 HDLC configuration: cometqHDLCTxCfg......................................................................... 104 HDLC transmitter: cometqTDPRData............................................................................... 104 HDLC transmitter: cometqTDPRCtl.................................................................................. 105 HDLC transmitter: cometqTDPRFIFOThreshCfg ............................................................. 105 HDLC transmitter: cometqTDPRTx .................................................................................. 106 HDLC receiver: cometqRDLCTerm .................................................................................. 106 HDLC receiver: cometqRDLCAddrMatch ......................................................................... 107 HDLC receiver: cometqRDLCFIFOThreshCfg ................................................................. 107 HDLC receiver: cometqRDLCRx ...................................................................................... 108 Inband loopack code detection: cometqIBCDActLpBkCfg ............................................... 109 Inband loopack code detection: cometqIBCDDeActLpBkCfg........................................... 110 Inband loopack code transmission: cometqIBCDTxCfg ................................................... 110 Bit Oriented Code transmission: cometqBOCTxCfg .........................................................111 Bit Oriented Code detection: cometqBOCRxCfg...............................................................111 Bit Oriented Code detection: cometqBOCRxGet ............................................................. 112 Serial Control........................................................................................................................... 112 Transmit per-channel serial controller: cometqTPSCEnable ........................................... 112 Transmit per-channel serial controller: cometqTPSCPCMCtl .......................................... 113 Receive per-channel serial controller: cometqRPSCEnable ............................................ 114 4.7 4.8 4.9 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 5 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Receive per-channel serial controller: cometqRPSCPCMCtl........................................... 115 Transmit Trunk Conditioning: cometqTxTrnkCfg .............................................................. 116 Receive Trunk Conditioning: cometqRxTrnkCfg............................................................... 117 Pattern receive and generation control: cometqPRGDCtlCfg .......................................... 117 Pattern receive and generation control: cometqPRGDPatCfg ......................................... 118 Pattern receive and generation control: cometqPRGDErrInsCfg..................................... 121 4.10 Interrupt Service Functions ..................................................................................................... 121 Configuring ISR Processing: cometqISRConfig ............................................................... 122 Getting the Interrupt Status Mask: cometqGetMask......................................................... 122 Setting the Interrupt Enable Mask: cometqSetMask ........................................................ 123 Clearing the Interrupt Enable Mask: cometqClearMask................................................... 123 Polling the Interrupt Status Registers: cometqPoll ........................................................... 124 Interrupt Service Routine: cometqISR .............................................................................. 124 Deferred Processing Routine: cometqDPR ...................................................................... 125 4.11 Status and Statistics Functions ............................................................................................... 126 Performance monitoring statistics: cometqForceStatsUpdate.......................................... 126 Performance monitoring statistics: cometqGetStats......................................................... 126 Framer status: cometqGetStatus ...................................................................................... 127 Status of line clocks: cometqLineClkStatGet .................................................................... 127 Pattern receive and generation control: cometqPRGDCntGet......................................... 128 Pattern receive and generation control: cometqPRGDGetBitCnt .................................... 128 Automatic performance report generation: cometqPmonSet ........................................... 128 Automatic performance report generation: cometqPmonReportGet................................ 129 4.12 Device Diagnostics.................................................................................................................. 130 Register access test: cometqTestReg .............................................................................. 130 Framer loopback: cometqLoopFramer ............................................................................. 130 DS0 loopback: cometqLoopTslots .................................................................................... 131 Analog transmitter bypass: cometqTxAnalogByp............................................................. 131 Analog transmitter bypass: cometqRxAnalogByp ............................................................ 132 4.13 Callback Functions .................................................................................................................. 132 Calling Back to the Application due to Interface events: cometqCbackIntf ...................... 133 Calling Back to the Application due to T1 / E1 Framer events: cometqCbackFramer ..... 133 Calling Back to the Application due to Signal Insertion / Extraction events: cometqCbackSigInsExt .............................................................................................. 134 Calling Back to the Application due to Performance Monitoring events: cometqCbackPMon ................................................................................................................................... 134 Calling Back to the Application due to Alarm Inband Communications events: cometqCbackAlarmInBand ........................................................................................ 135 Calling Back to the Application due to Serial Controller events: cometqCbackSerialCtl.. 135 5 Hardware Interface ........................................................................................................................... 136 5.1 Device I/O................................................................................................................................ 136 Reading from a Device Register: sysCometqRead.......................................................... 136 Writing to a Device Register: sysCometqWrite................................................................. 136 System-Specific Interrupt Servicing ........................................................................................ 137 Installing the ISR Handler: sysCometqISRHandlerInstall................................................. 137 ISR Handler: sysCometqISRHandler ............................................................................... 137 Removing the ISR Handler: sysCometqISRHandlerRemove........................................... 138 5.2 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 6 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual 6 RTOS Interface ................................................................................................................................. 139 6.1 Memory Allocation / De-Allocation .......................................................................................... 139 Allocating Memory: sysCometqMemAlloc ........................................................................ 139 Freeing Memory: sysCometqMemFree ............................................................................ 139 Setting memory: sysCometqMemSet ............................................................................... 140 Copying memory: sysCometqMemCpy ............................................................................ 140 Buffer Management................................................................................................................. 140 Starting Buffer Management: sysCometqBufferStart........................................................ 141 Getting an ISV Buffer: sysCometqISVBufferGet .............................................................. 141 Returning an ISV Buffer: sysCometqISVBufferRtn........................................................... 141 Getting a DPV Buffer: sysCometqDPVBufferGet ............................................................. 142 Returning a DPV Buffer: sysCometqDPVBufferRtn ......................................................... 142 Stopping Buffer Management: sysCometqBufferStop ...................................................... 142 Timers ..................................................................................................................................... 143 Sleeping a Task: sysCometqTimerSleep .......................................................................... 143 Preemption .............................................................................................................................. 143 Disabling Preemption: sysCometqPreemptDis ................................................................ 143 Re-Enabling Preemption: sysCometqPreemptEn ............................................................ 143 System-Specific DPR Routine................................................................................................. 144 Installing the DPR Task: sysCometqDPRTaskInstall ........................................................ 144 DPR Task: sysCometqDPRTask....................................................................................... 144 Removing the DPR Task: sysCometqDPRTaskRemove .................................................. 145 6.2 6.3 6.4 6.5 7 Porting the COMET-QUAD Driver..................................................................................................... 146 7.1 7.2 Driver Source Files.................................................................................................................. 146 Driver Porting Procedures....................................................................................................... 147 Step 1: Porting Driver RTOS Extensions.......................................................................... 147 Step 2: Porting Drivers to Hardware Platforms................................................................. 148 Step 3: Porting Driver Application Specific Elements ....................................................... 149 Step 4: Building the Driver ................................................................................................ 151 Appendix A: Coding Conventions............................................................................................................ 152 Appendix B: COMET-QUAD Error Codes ............................................................................................... 155 Appendix C: COMET-QUAD Events ....................................................................................................... 157 List of Terms ............................................................................................................................................ 169 Acronyms................................................................................................................................................. 170 Index ........................................................................................................................................................ 171 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 7 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual LIST OF FIGURES Figure 1: Driver External Interfaces................................................................................................13 Figure 2: Driver Architecture ..........................................................................................................16 Figure 3: Driver Software States ....................................................................................................21 Figure 4: Module Management Flow Diagram ...............................................................................23 Figure 5: Device Management Flow Diagram ................................................................................24 Figure 6: Interrupt Service Model ...................................................................................................25 Figure 7: Polling Service Model......................................................................................................27 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 8 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual LIST OF TABLES Table 1: COMET-QUAD Module Initialization Vector: sCMQ_MIV ...................................................29 Table 2: COMET-QUAD Device Initialization Vector: sCMQ_DIV.................................................30 Table 3: COMET-QUAD Analog Transmitter and Receiver Initialization: sCMQ_ANALOG_INIT .31 Table 4: COMET-QUAD Transmit and Receive Framer Initialization: sCMQ_FRAMER_INIT ......32 Table 5: COMET-QUAD Transmit and Receive Backplane Interface Initialization: sCMQ_BACKPLANE_INIT ............................................................................................33 Table 6: COMET-QUAD ISR Mask: sCMQ_ISR_MASK.................................................................34 Table 7: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_CDRC.................................................36 Table 8: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_RLPS ...............................................36 Table 9: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_JAT..................................................36 Table 10: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_SLIP .............................................37 Table 11: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_T1FRMR........................................37 Table 12: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_IBCD...............................................37 Table 13: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_ALMI .............................................37 Table 14: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_PDVD .............................................38 Table 15: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_XPDE .............................................38 Table 16: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_RBOC .............................................38 Table 17: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_E1TRAN .........................................39 Table 18: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_E1FRMR .........................................39 Table 19: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_TDPR .............................................41 Table 20: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_RDLC .............................................41 Table 21: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_PRBS .............................................42 Table 22: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_SIGX .............................................42 Table 23: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_PMON .............................................42 Table 24: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_BTIF .............................................43 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 9 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Table 25: COMET-QUAD Transmit Jitter Attenuator Configuration: sCMQ_CFG_TX_JAT...........43 Table 26: COMET-QUAD Receive Jitter Attenuator Configuration: sCMQ_CFG_RX_JAT............44 Table 27: COMET-QUAD Receive Clock Configuration: sCMQ_CFG_RX_CLK ............................44 Table 28: COMET-QUAD Line Side Interface Analog Transmitter Configuration: sCMQ_CFG_TX_ANALOG...............................................................................................46 Table 29: COMET-QUAD Analog Receiver Configuration: sCMQ_CFG_RX_ANALOG ..................49 Table 30: COMET-QUAD Backplane Access Configuration: sCMQ_BACKPLANE_ACCESS_CFG 52 Table 31: COMET-QUAD Backplane Receive Frame Configuration: sCMQ_CFG_BRIF_FRM.....52 Table 32: COMET-QUAD Backplane Transmit Frame Configuration: sCMQ_CFG_BTIF_FRM....53 Table 33: COMET-QUAD H-MVIP Configuration: sCMQ_CFG_HMVIP .........................................54 Table 34: COMET-QUAD Receive Elastic Store Configuration: sCMQ_CFG_RX_ELST ...............55 Table 35: COMET-QUAD T1 Transmit Framer Configuration: sCMQ_CFG_T1TX_FRM ...............55 Table 36: COMET-QUAD T1 Receive Framer Configuration: sCMQ_CFG_T1RX_FRM ................56 Table 37: COMET-QUAD E1 Transmit Framer Configuration: sCMQ_CFG_E1TX_FRM ...............57 Table 38: COMET-QUAD E1 Receive Framer Configuration: sCMQ_CFG_E1RX_FRM ................58 Table 39: COMET-QUAD HDLC Link Extraction/Insertion Location Configuration: sCMQ_CFG_HDLC_LINK...............................................................................................59 Table 40: COMET-QUAD HDLC Receiver Configuration: sCMQ_CFG_HDLC_RX ........................60 Table 41: COMET-QUAD HDLC Receiver Configuration: sCMQ_CFG_HDLC_TX ........................60 Table 42: COMET-QUAD Clock Status Structure: sCMQ_CLK_STATUS ......................................61 Table 43: COMET-QUAD Framer Statistics: sCMQ_FRM_CNTS ...................................................61 Table 44: COMET-QUAD Framer Status: sCMQ_FRM_STATUS ...................................................61 Table 45: COMET-QUAD T1 Automatic Performance Monitoring Message: sCMQ_STAT_APRM62 Table 46: COMET-QUAD Module Data Block: sCMQ_MDB...........................................................63 Table 47: COMET-QUAD Device Data Block: sCMQ_DDB............................................................64 Table 48: COMET-QUAD Interrupt Service Vector: sCMQ_ISV ...................................................65 Table 49: COMET-QUAD Deferred Processing Vector: sCMQ_DPV.............................................66 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 10 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Table 50: Variable Type Definitions .............................................................................................152 Table 51: Naming Conventions ...................................................................................................152 Table 52: File Naming Conventions ............................................................................................153 Table 53: COMET-QUAD Error Codes ........................................................................................155 Table 54: COMET-QUAD DPV Event bit masks..........................................................................157 Table 55: COMET-QUAD Events for Interface Callbacks...........................................................162 Table 56: COMET-QUAD Events for Framer Callbacks ..............................................................164 Table 57: COMET-QUAD Events for Alarm and InBand Communications Callbacks.................166 Table 58: COMET-QUAD Events for Signal Extraction Callbacks...............................................167 Table 59: COMET-QUAD Events for Performance Monitoring Callbacks ..................................167 Table 60: COMET-QUAD Events for Serial Controller Callbacks...............................................168 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 11 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Introduction 1 INTRODUCTION The following sections of the COMET and COMET-QUAD driver manual describe the COMET and COMET-QUAD device driver. Throughout the document, the device driver will be referred to as the COMET-QUAD device driver. However, the driver supports the COMET through the same set of API calls. Sections 4 and 5 of this document outline how each API function within the driver applies to both COMET and COMET-QUAD devices on a per API function basis. The code provided throughout this document is written in the C language. This has been done to promote greater driver portability to other embedded Real Time Operating Systems (section 6) and hardware environments (section 5). Section 2 of this document, Software Architecture, defines the software architecture of the COMET-QUAD device driver by including a discussion of the driver's external interfaces and its main components. The Data Structure information in section 3 describes the elements of the driver that configure or control its behavior. Included here are the constants, variables and structures that the COMET-QUAD Device Driver uses to store initialization, configuration and statistics information. Section 4 provides a detailed description of each function that is a member of the COMET-QUAD driver Application Programming Interface (API). The section outlines function calls that hide device-specific details and application callbacks that notify the user of significant device events. For your convenience, section 7 of this manual provides a brief guide for porting the COMETQUAD device driver to your hardware and RTOS platform. In addition, an extensive Appendix (page 152) and Index (page 171) provide you with useful reference information. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 12 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture 2 SOFTWARE ARCHITECTURE This section of the manual describes the software architecture of the COMET-QUAD device driver. Details of the software architecture include a discussion of the driver's external interfaces and its main components. 2.1 Driver External Interfaces Figure 1 illustrates the external interfaces defined for the COMET-QUAD device driver. Figure 1: Driver External Interfaces Application Function Calls Application Callbacks Service Callbacks COMET-Quad Device Driver RTOS Service Calls Hardware Interrupts Register Accesses COMET-Quad/COMET Devices Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 13 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Application Programming Interface The Driver Application Programming Interface (API) is a list of high-level functions that can be invoked by application programmers to configure, control and monitor COMET-QUAD and COMET devices. The API includes the following functions: * * * * Initialize the device(s) Perform diagnostic tests Validate configuration information Retrieve status and statistics information The driver API functions use the services of the other driver components to provide this systemlevel functionality to the application programmer. The driver API also consists of callback routines that are used to notify the application of significant events that take place within the device(s) and module. Real-Time Operating System (RTOS) Interface The driver's RTOS interface provides functions that let the driver use the RTOS's memory, interrupt, and pre-emption services. These RTOS interface functions perform the following tasks for the driver: * * * Allocate and de-allocate memory Manage buffers for the ISR and the DPR Enable and disable pre-emption The RTOS interface also includes service callbacks. These are functions installed by the driver using RTOS service calls such as installing interrupts. These service callbacks are invoked when an interrupt occurs. Hardware Interface The hardware interface provides functions that read from and write to the device registers. The hardware interface also provides a template for an ISR that the driver calls when the device raises a hardware interrupt. You must modify this function based on the interrupt configuration of your system. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 14 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture 2.2 Main Components Figure 2 illustrates the top-level architectural components of the COMET-QUAD device driver: * * * * * * * * * * Module data-block and device data-blocks Module and device management Interrupt servicing Status and statistics Interface configuration T1/E1 framers Signal Insertion/Extraction Alarm Control and Inband Communication Serial Control Device Diagnostics and Loopbacks Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 15 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Figure 2: Driver Architecture Application Function Calls Service Callbacks RTOS Interface Service Calls RTOS Application Callbacks Interrupt Servicing Deferred Processing Routine Driver API Module & Device Management Interface Configuration T1/E1 Framers Signal Insertion/ Extraction Alarm Control & Inband Communication Serial Control Status & Statistics Device Diagnostics Module Data Block Device Data Blocks ....... Interrupt Context Interrupt Service Routine Hardware Interface Hardware Interrupts Register Accesses COMET & COMET-Quad Devices Module Data-Block and Device Data-Blocks The Module Data-Block (MDB) is the top layer data structure created by the COMET-QUAD driver to store context information about the driver module, such as: * * * * Module state Maximum number of devices The DDB(s) The initialization profile(s) The Device Data-Block (DDB) is contained in the MDB, and initialized by the driver module for each COMET-QUAD or COMET device that is registered. There is one DDB per device and there is a limit on the number of DDBs available. That limit is set by the USER when the module is initialized. The DDB is used to store context information about one device, such as: * * * Device state Control information Initialization parameters Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 16 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture * Callback function pointers Module and Device Management The module and device management block provides the following: * * Module management that takes care of initializing the driver, allocating memory and all RTOS resources needed by the driver Device management that is responsible for providing basic read/write routines and initializing a device in a specific configuration, as well as enabling the device general activity For more information on the module and device states see the state diagram on page 21. For typical module and device management flow diagrams see pages 23 and 24 respectively. Interrupt Servicing/Polling Interrupt Servicing is an optional feature. The user can disable device interrupts and instead poll the device periodically to monitor status and check for alarm/error conditions. The COMETQUAD driver provides: * * An Interrupt-Service Routine (ISR) called cometqISR that checks for valid interrupt conditions A Deferred Processing Routine (DPR) called cometqDPR that processes any interrupt condition gathered by the ISR See section 2.5 for a detailed explanation of the interrupt-servicing model. Status and Statistics Collection This section contains functions to gather statistics and monitor the status of the device. Specifically, this interface provides functionality to examine error counts such as framing errors, CRC errors, and line code violations as well as clock status information and pseudo-random generator error counts. This API allows the user to monitor the status of each framer on the device. The device is polled for the following error conditions: * * * * * * Loss of signal Loss of frame alignment Alarm Indication Signal (AIS) Yellow or E1 RAI alarm E1 loss of signaling multiframe alignment E1 loss of CRC-4 multiframe alignment 17 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture * E1 timeslot 16 RAI Also, transmission of T1 ESF FDL automatic performance report messages (APRM) is handled through this API. The user can perform the following APRM functions through the status and statistics collection API: * * Enable/disable automatic performance report insertion into the FDL. For COMET devices, manual insertion of the performance report can be forced by these APIs View the current APRM message to be sent on the FDL Interface Configuration This section of the driver allows the user to configure both the T1/E1 line and the receive and transmit backplane interfaces. Specifically, these functions provide the following: * * * * * * * * * * Selection of the receive and transmit line coding scheme: B8ZS, HDB3, or AMI Programming of transmit pulse waveform from predefined Long/Short haul waveform template or allow USER defined Transmitter fuse programming Selection of Clock & Data Recovery algorithm for low or high frequency jitter tolerance Receive and transmit jitter attenuation enable/disable and configuration Analog and digital loss of signal (LOS) configuration Backplane clock master or slave mode selection for the transmit and receive interfaces Backplane data format (channelized, full frame) and the clock rate configuration Frame pulse master or slave and frame pulse offset configuration Receive and transmit backplane H-MVIP or H-MVIP CCS mode selection T1/E1 Framers This section of the driver contains functions that are used to configure the T1/E1 receive and transmit framers. These functions provide the following: * * * * Selection between global T1 or E1 mode Configuration of the T1 framers to transmit or receive in SF, ESF, T1DM, SLC96 or TTC JTG704 mode Configure the E1 framers to transmit or receive in CRC-4 multiframe format as well as enable channel associative signaling insertion and receiver signaling multiframe alignment Retrieve and transmit E1 international, national, and extra bits. In addition to configuring the relevant framer, these functions configure the complete receive and transmit data path based on the receive and transmit framing modes specified. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 18 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Signal Insertion / Extraction The signal insertion/extraction API provide functionality that monitors channel associative signaling (CAS) in the receive stream. These API provide the following functionality: * * * Extraction of CAS from an E1 signaling multiframe or from a T1 ESF or SF frame Monitoring signaling state transitions Control on a per-timeslot basis, bit fixing, data inversion, and signal state debouncing Alarm Control and Inband Communications This section of the driver contains functions that are used for detection and insertion of Inband Communication codes, BOC codes, and alarms. Specifically, these functions perform the following: * * * * * * Transmission of AIS, yellow alarms, E1 y-bit alarms, and E1 timeslot 16 AIS Enabling or disabling of automatic device alarm response upon detection of yellow alarm, red alarm, out-of frame, or loss of signal Detection and transmission of BOC codes transmitted in the T1 FDL channel in ESF framing format Configuration of transmit and receive HDLC data links Configuration of T1 FDL to transmit one of 63 possible BOC codes Transmission and detection of T1 Inband Loopback codes Serial Controller This section contains functions that are used to configure the receive and transmit serial controllers. Specifically, these functions perform the following: * * * DS0 control of PCM data manipulation and digital milliwatt pattern insertion Pseudo-random pattern generation and detection Idle code insertion into T1 or E1 stream Device Diagnostics The device diagnostics API can be used to isolate/identify problems within the device and its interfaces. Specifically, these functions perform: * * * * Device register read/write test Backplane loopback Line loopback Payload loopback Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 19 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture * * Per-channel loopback Analog transmitter and receiver bypass Specific Callback Functions Callback functions are available to the application for event notification from the device driver. Applications will be notified via the callback functions for selected events of interest such as: * * * * * * * Alarm conditions Statistics Diagnostics Line coding and conditioning T1/E1 Framer Data Link Performance Monitoring 2.3 Software States Figure 3 shows the software state diagram for the COMET-QUAD driver. State transitions occur on the successful execution of the corresponding transition functions shown below. State information helps maintain the integrity of the MDB and DDB(s) by controlling the set of operations allowed in each state. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 20 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Figure 3: Driver Software States cometqModuleOpen Idle cometqModuleClose Start cometqModuleStop cometqModuleStart cometqModuleClose Ready MODULE STATES Start cometqAdd cometqDelete Present cometqReset cometqInit cometqActivate Inactive cometqDeActivate PER-DEVICE STATES Active cometqReset Module States The following is a description of the COMET-QUAD module states. See section 4.1 for a detailed description of the API functions that are used to change the module state. The module states are: Start The driver module has not been initialized. In this state the driver does not hold any RTOS resources (memory, timers, etc), has no running tasks, and performs no actions. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 21 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Idle The driver module has been initialized successfully. The Module Initialization Vector (MIV) has been validated; the Module Data Block (MDB) has been allocated and loaded with current data; the per-device data structures have been allocated; and the RTOS has responded without error to all the requests sent to it by the driver. Ready This is the normal operating state for the driver module. This means that all RTOS resources have been allocated and the driver is ready for devices to be added. The driver module remains in this state while devices are in operation. Device States The following is a description of the COMET or COMET-QUAD per-device states. The state that is mentioned here is the software state as maintained by the driver, and not as maintained inside the device itself. See section 4.1 for a detailed description of the API functions that are used to change the per-device state. Start The device has not been initialized. In this state the device is unknown to the driver and performs no actions. There is a separate flow for each device that can be added, and they all start here. Present The device has been successfully added. A Device Data Block (DDB) has been associated with the device and updated with the user context; and a device handle has been given to the USER. In this state, the device performs no actions. Inactive In this state the device is configured but all data functions are de-activated, including interrupts and alarms, and status and statistics functions. Active This is the normal operating state for the device. In this state, interrupt servicing or polling is enabled. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 22 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture 2.4 Processing Flows This section of the manual describes the main processing flows of the COMET-QUAD driver components. The flow diagrams presented here illustrate the sequence of operations that take place for different driver functions. The diagrams also serve as a guide to the application programmer by illustrating the sequence in which the application must invoke the driver API. Module Management The following diagram illustrates the typical function call sequences that occur when either initializing or shutting down the COMET-QUAD driver module. Figure 4: Module Management Flow Diagram START Performs module level initialization of the driver. Validates the Module Initialization Vector (MIV). Allocates memory for the MDB and all its components (i.e. all the memory needed by the driver) and then initializes the contents of the MDB with the validated MIV. Performs module level startup of the driver. This involves allocating RTOS resources such as semaphores and timers and installing the ISR handler and DPR task. Registers an initialization profile. This allows the user to store pre-defined parameter vectors that are validated ahead of time. When the deviceinitialization function is invoked, only a profile number need to be passed. This method simplifies and expedites the above operations. Performs all device level functions here (add, init, activate, de-activate, reset, delete,...) cometqDeleteInitProfile De-registers an initialization profile previously registered with the driver. cometqModuleOpen cometqModuleStart cometqAddInitProfile cometqModuleStop Performs Module level shutdown of the driver. This involves deleting all devices currently installed and de-allocating all timers and semaphores as well as removing the ISR handler and DPR task. Performs module level shutdown of the driver. De-allocates all the driver's memory. cometqModuleClose END Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 23 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Device Management The following figure shows the typical function call sequences that the driver uses to add, initialize, re-initialize, and delete a COMET or COMET-QUAD device. Figure 5: Device Management Flow Diagram START cometqAdd Detects the new device in hardware, assigns a DDB to the new device and stores the user's context for the device. Returns a device handle to the user. Applies a reset to the device and initializes the device registers and associated RAMs based on the DIV passed by the user. The user may only pass a profile number, which corresponds to a previously saved & validated set of configurations (by using cometqSetInitProfile). cometqInit cometqActivate Prepares the device for normal operation by enabling interrupts and other global enables. ISR routines are installed when the module is started using sysCometqISRInstallHandler. The device is now operational and all other APIs can be invoked. cometqReset In order to re-initialize the device, reset the device using spectraReset and go through the initialization sequence again. cometqDeactivate De-activates the device and removes it from normal operation. This involves disabling the device interrupts. ISR routines for this device are removed using sysCometqISRRemoveHandler when the module is closed. cometqReset Applies a software reset to the device to put it in its default startup state. cometqDelete Removes the device from the list of devices being controlled by the COMETQ driver. This function de-allocates the device context information for the device being deleted. END Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 24 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture 2.5 Interrupt Servicing The COMET-QUAD driver services device interrupts using an interrupt service routine (ISR) that traps interrupts. It also contains a deferred processing routine (DPR) that actually processes the interrupt conditions and clears them. This architecture enables the ISR to execute quickly and then exit. Most of the time-consuming processing of the interrupt conditions is deferred to the DPR by queuing the necessary interrupt-context information to the DPR task. The DPR function runs in the context of a separate task within the RTOS. Note: Since the DPR task processes potentially serious interrupt conditions, you should set the DPR task's priority higher than the application task interacting with the COMET-QUAD driver. The driver provides system-independent functions, cometqISR and cometqDPR. You must fill in the corresponding system-specific functions, sysCometqISRHandler and sysCometqDPRTask. The system-specific functions isolate the system-specific communication mechanism (between the ISR and DPR) from the system-independent functions, cometqISR and cometqDPR. Figure 6 illustrates the interrupt service model used in the COMET-QUAD driver design. Figure 6: Interrupt Service Model Interrupt Context Information sysCometqISRHandler cometqISR sysCometqDPRTask cometqDPR Indication Callbacks Application Note: Instead of using an interrupt service model, you can use a polling service model in the COMET-QUAD driver to process the device's event-indication registers (see page 26). Calling cometqISR An interrupt handler function (which is system dependent), must call cometqISR. But first, the low-level interrupt-handler function must trap the device interrupts. You must implement this function (sysCometqISRHandler) to fit your own system. For an example implementation of the interrupt handler and its prototype, see page 137. The interrupt handler that you implement (sysCometqISRHandler) is installed in the interrupt vector table of the system processor. It is called when one or more COMET or COMET-QUAD devices interrupt the processor. The interrupt handler then calls cometqISR for each device in the active state that has interrupt processing enabled. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 25 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture The cometqISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the COMET or COMET-QUAD. If at least one valid interrupt condition is found then cometqISR fills an Interrupt Service Vector (ISV) with this status information as well as the current device handle. The cometqISR function also clears and disables all the interrupts detected by the device. The sysCometqISRHandler function is then responsible for sending this ISV buffer to the DPR task. Note: Normally you should save the status information for deferred processing by implementing a message queue. The interrupt handler sends the status information to the queue by sysCometqISRHandler. Calling cometqDPR The sysCometqDPRTask function is a system specific function that runs as a separate task within the RTOS. You should set the DPR task's priority higher than the application task(s) interacting with the COMET-QUAD driver. In the message-queue implementation model, this task has an associated message queue. The task waits for messages from the ISR on this message queue. When a message arrives, sysCometqDPRTask calls the DPR (cometqDPR) with the received ISV. Then cometqDPR processes the status information and takes appropriate action based on the specific interrupt condition detected. The nature of this processing can differ from system to system. Therefore, cometqDPR calls different indication callbacks for different interrupt conditions. Typically, you should implement these callback functions as simple message posting functions that post messages to an application task. However, you can implement the indication callback to perform processing within the DPR task context and return without sending any messages. In this case, ensure that this callback function does not call any API functions that would change the driver's state, such as cometqDelete. In addition, ensure that the callback function is non-blocking because the DPR task executes while COMET or COMET-QUAD interrupts are disabled. You can customize these callbacks to suit your system. See page 131 for example implementations of the callback functions. Note: Since the cometqISR and cometqDPR routines themselves do not specify a communication mechanism, you have full flexibility in choosing a communication mechanism between the two. A convenient way to implement this is to use a message queue, which is a service that most RTOSs provide. You must implement the two system specific functions, sysCometqISRHandler and sysCometqDPRTask. When the driver calls sysCometqISRHandlerInstall, the application installs sysCometqISRHandler in the interrupt vector table of the processor, and the sysCometqDPRTask function is spawned as a task by the application. The sysCometqISRHandlerInstall function also creates the communication channel between sysCometqISRHandler and sysCometqDPRTask. This communication channel is most commonly a message queue associated with sysCometqDPRTask. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 26 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Software Architecture Similarly, during removal of interrupts, the driver removes sysCometqISRHandler from the microprocessor's interrupt vector table and deletes the task associated with sysCometqDPRTask. As a reference, the driver provides example implementations of the interrupt installation and removal functions on pages 137 and 152. You can modify these functions to suit your specific needs. Calling cometqPoll Instead of using an interrupt service model, you can use a polling service model in the COMETQUAD driver to process the device's event-indication registers. Figure 7 illustrates the polling service model used in the COMET-QUAD driver design. Figure 7: Polling Service Model cometqPoll Interrupt Context Information Indication Callbacks cometqDPR Application cometqISR In polling mode, the application is responsible for calling cometqPoll often enough to service any pending error or alarm conditions. When cometqPoll is called, the cometqISR function is called internally. The cometqISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the COMET or COMET-QUAD device. If at least one valid interrupt condition is found then cometqISR fills an Interrupt Service Vector (ISV) with this status information as well as the current device handle. The cometqISR function also clears and disables all the device's interrupts detected. In polling mode, cometqPoll then invokes cometqDPR directly and passes the ISV buffer (returned by cometqISR) as an input parameter. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 27 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures 3 DATA STRUCTURES This section of the manual describes the elements of the driver that configure or control its behavior. Included here are the constants, variables and structures that the COMET-QUAD Device Driver uses to store initialization, configuration and statistics information. For more information on naming conventions, please see Appendix A (page 152). 3.1 Constants The following Constants are used throughout the driver code: * * driver. This constant must not be changed without a thorough analysis of the consequences to the driver code. CMQ_MAX_INIT_PROFS: this defines the maximum number of profiles that can be supported * * * by this driver. CMQ_MOD_START, CMQ_MOD_IDLE, CMQ_MOD_READY: these contain the three possible Module states (stored in the MDB as stateModule). CMQ_START, CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE: these contain the four possible Device states (stored in the DDB as stateDevice). 3.2 Structures Passed by the Application These structures are defined for use by the application and are passed as an argument to functions within the driver. These structures are the Module Initialization Vector (MIV), the Device Initialization Vector (DIV) and the ISR mask. The following explains their workings in detail. Module Initialization Vector: MIV Passed via the cometqModuleOpen call, this structure contains all the information needed by the driver to initialize and connect to the RTOS. * The variable maxDevs is used to inform the driver how many devices will be operating concurrently during this session. The number is used to calculate the amount of memory that will be allocated to the driver. The maximum value that can be passed is CMQ_MAX_DEVS (see section 3.1). Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 28 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures * The variable maxInitProfs is used to inform the driver how many profiles will be used during this session. The number is used to calculate the amount of memory that will be allocated to the driver. The maximum value that can be passed is CMQ_MAX_INIT_PROFS (see section 3.1). Table 1: COMET-QUAD Module Initialization Vector: sCMQ_MIV Field Name perrModule Field Type INT4 * Field Description (pointer to) errModule (see description in the MDB) Maximum number of devices supported during this session Maximum number of initialization profiles maxDevs UINT2 maxInitProfs UINT2 Device Initialization Vector: DIV Passed via the cometqInit call, this structure contains all the information needed by the driver to initialize a COMET or COMET-QUAD device. This structure is also passed via the cometqSetInitProfile call when used as an initialization profile. Note that when initializing COMET-QUAD devices with a DIV, the hardware initialization specified in the DIV is applied to all four quadrants. * * valid indicates that this initialization profile has been properly initialized and may be used by the USER. This field should be ignored when the DIV is passed directly. pollISR is a flag that indicates the type of interrupt servicing the driver is to use. The choices are `polling' (CMQ_POLL_MODE), and `interrupt driven' (CMQ_ISR_MODE). When configured in polling the Interrupt capability of the device is NOT used, and the USER is responsible for calling cometqPoll periodically. The actual processing of the event information is the same for both modes. cbackFramer, cbackIntf, cbackAlarmInBand, cbackPMon, cbackSerialCtl, and cbackSigInsExt are used to pass the address of application functions that will be used * by the DPR to inform the application code of pending events. If these fields are set as NULL, then any events that might cause the DPR to `call back' the application will be processed during ISR processing but ignored by the DPR. * initDevice is a flag that indicates whether or not the hardware is to be initialized based on the information in the analogInit, framerInit, and backplaneInit members of the DIV. If initDevice is not set, the hardware remains in its reset state upon initialization. When set, the device is initialized as appropriate for the values of the hardware initialization members. This field is only used when the DIV is not being used as an initialization profile. When adding an initialization profile, the hardware configuration must always be valid. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 29 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 2: COMET-QUAD Device Initialization Vector: sCMQ_DIV Field Name valid pollISR Field Type UINT2 eCMQ_ISR_MODE Field Description Indicates that this structure is valid Indicates type of interrupt processing (ISR mode or polling) Address of the callback function for Interface Events Address of the callback function for Framer Events Address of the callback function for Alarm Inband Events Address of the callback function for Signal Insertion and Extraction Events Address of the callback function for Performance Monitoring Events Address of the callback function for Serial Control Events Flag to indicate whether or not to apply hardware configuration (analogInit, framerInit, backplaneInit) to the device. If this flag is not set, the device is left in its reset state. By setting this flag, analogInit, framerInit, and backplaneInit are all applied to the device. This field is not used when the DIV is used as an initialization profile. Initialization configuration for the analog interfaces. Initialization configuration for the transmit and receive framers. Initialization configuration for the transmit and receive backplane interfaces. cbackIntf CMQ_CBACK cbackFramer CMQ_CBACK cbackAlarmInBand CMQ_CBACK cbackSigInsExt CMQ_CBACK cbackPMon CMQ_CBACK cbackSerialCtl CMQ_CBACK initDevice UINT1 analogInit sCMQ_ANALOG_INIT framerInit sCMQ_FRAMER_INIT backplaneInit sCMQ_BACKPLANE_I NIT Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 30 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures DIV Sub-structures The following structures are members of the device initialization vector (DIV) structure. They have the function of initializing the analog transmitter and receiver, the transmit and receive framers, and the transmit and receive backplane interfaces respectively. The contents of these structures are not applied to the device hardware when the initDevice member of the DIV is set to false. When this member is true, the hardware configuration is applied to the device. Initialization of the framers includes configuring all blocks within the device to conform to the framing modes that are given in the framer initialization structure. Backplane hardware is programmed as recommended in the Operations section of the COMET and COMET-QUAD data sheet. The transmit and receive analog structure allows the user to select the transmit pulse waveform and the receive equalizer RAM from a table stored within the driver. These tables correspond to the values specified in the Operations section of the COMET and COMET-QUAD data sheet. Table 3: COMET-QUAD Analog Transmitter and Receiver Initialization: sCMQ_ANALOG_INIT Field Name txLineBuildOut Field Type eCMQ_TX_LBO Field Description Selects XLPG line build out and waveform scale factor. Choose from predefined tables and corresponding waveform scale factors stored within the driver (as defined in the COMET and COMETQUAD data sheet): CMQ_TX_LBO_T1_LONG_HAUL_0DB, CMQ_TX_LBO_T1_LONG_HAUL_7_5DB, CMQ_TX_LBO_T1_LONG_HAUL_15DB, CMQ_TX_LBO_T1_LONG_HAUL_22_5DB, CMQ_TX_LBO_T1_LONG_HAUL_TR62411_0DB, CMQ_TX_LBO_T1_SHORT_HAUL_110FT, CMQ_TX_LBO_T1_SHORT_HAUL_220FT, CMQ_TX_LBO_T1_SHORT_HAUL_330FT, CMQ_TX_LBO_T1_SHORT_HAUL_440FT, CMQ_TX_LBO_T1_SHORT_HAUL_550FT, CMQ_TX_LBO_T1_SHORT_HAUL_660FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_110FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_220FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_330FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_440FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_550FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_660FT, CMQ_TX_LBO_E1_75OHM, CMQ_TX_LBO_E1_120OHM txEnable UINT1 Set to 1 to enable transmitter, otherwise analog outputs are left in high impedance state Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 31 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name rxEqualizerTable Field Type eCMQ_RX_LINE _EQ Field Description Selects one of predefined RLPS equalizer RAMs (as defined in the COMET and COMET-QUAD data sheet): CMQ_RX_LINE_EQ_RAM_T1, CMQ_RX_LINE_EQ_RAM_E1 csuClkMode eCMQ_CSU_SVC _CLK Selects the clock synthesis unit (CSU) operational mode based on the XCLK frequency: CMQ_XCLK_2048_TXCLK_2048, CMQ_XCLK_1544_TXCLK_1544, CMQ_XCLK_2048_TXCLK_1544 Table 4: COMET-QUAD Transmit and Receive Framer Initialization: sCMQ_FRAMER_INIT Field Name txFramerMode Field Type eCMQ_FRAME_MODE Field Description Selects a T1 or E1 framing format for the transmit framer: CMQ_FRM_MODE_E1, CMQ_FRM_MODE_E1_CRC_MFRM, CMQ_FRM_MODE_E1_UNFRAMED, CMQ_FRM_MODE_T1_SF, CMQ_FRM_MODE_T1_DM, CMQ_FRM_MODE_T1_SLC96, CMQ_FRM_MODE_T1_DM_FDL, CMQ_FRM_MODE_T1_ESF, CMQ_FRM_MODE_T1_SF_JPN_ALARM, CMQ_FRM_MODE_T1_DM_JPN_ALARM, CMQ_FRM_MODE_T1_SLC96_JPN_ALARM, CMQ_FRM_MODE_T1_DM_FDL_JPN_ALARM, CMQ_FRM_MODE_T1_JT_G704, CMQ_FRM_MODE_T1_UNFRAMED Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 32 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name rxFramerMode Field Type eCMQ_FRAME_MODE Field Description Selects a T1 or E1 framing format for the receive framer: CMQ_FRM_MODE_E1, CMQ_FRM_MODE_E1_CRC_MFRM, CMQ_FRM_MODE_E1_UNFRAMED, CMQ_FRM_MODE_T1_SF, CMQ_FRM_MODE_T1_DM, CMQ_FRM_MODE_T1_SLC96, CMQ_FRM_MODE_T1_DM_FDL, CMQ_FRM_MODE_T1_ESF, CMQ_FRM_MODE_T1_SF_JPN_ALARM, CMQ_FRM_MODE_T1_DM_JPN_ALARM, CMQ_FRM_MODE_T1_SLC96_JPN_ALARM, CMQ_FRM_MODE_T1_DM_FDL_JPN_ALARM, CMQ_FRM_MODE_T1_JT_G704, CMQ_FRM_MODE_T1_UNFRAMED Note that both the transmit and receive framers must be operating in either T1 or E1. Table 5: COMET-QUAD Transmit and Receive Backplane Interface Initialization: sCMQ_BACKPLANE_INIT Field Name backplaneTxMode Field Type eCMQ_BACK PLANE_TX_ MODE Field Description Selects the configuration of the transmit backplane interface: CMQ_BACKPLANE_TX_CLOCK_MASTER_FULL_T1E1, CMQ_BACKPLANE_TX_CLOCK_MASTER_Nx64, CMQ_BACKPLANE_TX_CLOCK_MASTER_CLEAR_CHAN CMQ_BACKPLANE_TX_CLOCK_SLAVE_FULL_T1E1, CMQ_BACKPLANE_TX_CLOCK_SLAVE_CLEAR_CHAN, CMQ_BACKPLANE_TX_CLOCK_SLAVE_HMVIP (COMET-QUAD only), CMQ_BACKPLANE_TX_CLOCK_SLAVE_FULL_T1E1_H MVIP_CCS (COMET-QUAD only) For a detailed description of each of these configurations, consult the device data sheet. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 33 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name backplaneRxMode Field Type eCMQ_BACK PLANE_RX_ MODE Field Description Selects the configuration of the receive backplane interface: CMQ_BACKPLANE_RX_CLOCK_MASTER_FULL_T1E1, CMQ_BACKPLANE_RX_CLOCK_MASTER_Nx64, CMQ_BACKPLANE_RX_CLOCK_MASTER_CLEAR_CHAN CMQ_BACKPLANE_RX_CLOCK_SLAVE_FULL_T1E1, CMQ_BACKPLANE_RX_CLOCK_SLAVE_HMVIP (COMET-QUAD Only) CMQ_BACKPLANE_RX_CLOCK_SLAVE_FULL_T1E1_H MVIP_CCS (COMET-QUAD only) For a detailed description of each of these configurations, please consult the device data sheet. CCSTimeslot15 UINT1 If backplaneTxMode is CMQ_BACKPLANE_TX_CLOCK_SLAVE_FULL_T1E1_H MVIP_CCS, this member enables CCS insertion into timeslot 15 CCSTimeslot16 UINT1 If backplaneTxMode is CMQ_BACKPLANE_TX_CLOCK_SLAVE_FULL_T1E1_H MVIP_CCS, this member enables CCS insertion into timeslot 16 CCSTimeslot31 UINT1 If backplaneTxMode is CMQ_BACKPLANE_TX_CLOCK_SLAVE_FULL_T1E1_H MVIP_CCS, this member enables CCS insertion into timeslot 31 ISR Enable/Disable Mask Passed via the cometqSetMask, cometqGetMask and cometqClrMask calls, this structure contains all the information needed by the driver to enable and disable any of the interrupts on the COMET or COMET-QUAD. ISR Mask Top-Level Structure Table 6: COMET-QUAD ISR Mask: sCMQ_ISR_MASK Field Name cdrc Field Type sCMQ_ISR_MASK_CDRC[4] Field Description Clock & data recovery mask Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 34 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name rjat tjat rxSlip txSlip btif Field Type sCMQ_ISR_MASK_JAT[4] sCMQ_ISR_MASK_JAT[4] sCMQ_ISR_MASK_SLIP[4] sCMQ_ISR_MASK_SLIP[4] sCMQ_ISR_MASK_BTIF[4] Field Description Receive jitter attenuation mask Transmit jitter attenuation mask Receive elastic store slip mask Transmit elastic store slip mask Transmit backplane interface signal and data parity detection mask T1 receive framer mask Inband communications loopback mask Performance monitoring mask Alarm integrator mask Receive pulse density violation mask Transmit pulse density enforcer mask Receive BOC mask Transmit BOC interrupt enable (COMET-QUAD Only) E1 transmit section mask E1 receive framer mask Receive signal elastic store slip mask (COMET-QUAD Only) Transmit signal elastic store slip mask (COMET-QUAD Only) HDLC transmitter mask HDLC receiver mask Pseudo random binary sequence mask RLPS analog loss of signal mask t1Frmr ibcd sCMQ_ISR_MASK_T1FRMR[4] sCMQ_ISR_MASK_IBCD[4] pmon almi pdvd xpde rboc tboc sCMQ_ISR_MASK_PMON[4] sCMQ_ISR_MASK_ALMI[4] sCMQ_ISR_MASK_PDVD[4] sCMQ_ISR_MASK_XPDE[4] sCMQ_ISR_MASK_RBOC[4] UINT1[4] e1Tran e1Frmr rxCCSSlip sCMQ_ISR_MASK_E1TRAN[4] sCMQ_ISR_MASK_E1FRMR[4] sCMQ_ISR_MASK_SLIP[4] txCCSSlip sCMQ_ISR_MASK_SLIP[4] tdpr rdlc prbs rlps sCMQ_ISR_MASK_TDPR[4] sCMQ_ISR_MASK_RDLC[4] sCMQ_ISR_MASK_PRBS[4] sCMQ_ISR_MASK_RLPS[4] Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 35 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name aprmEn sigx Field Type UINT1[4] sCMQ_ISR_MASK_SIGX[4] Field Description Auto performance report mask Signaling extractor mask ISR Mask Sub-structures Table 7: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_CDRC Field Name lcvEn losEn lcsdEn zndEn altLosEn atlLosInd losInd Field Type UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 Field Description CDRC line code violation detection enable CDRC loss of signal detection enable CDRC line code signature detection enable CDRC excess zero detection enable CDRC alternate loss of signal detection enable CDRC alternate loss of signal status indicator CDRC loss of signal status indicator Table 8: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_RLPS Field Name losEn losInd Field Type UINT1 UINT1 Field Description RLPS loss of signal detection enable RLPS loss of signal status indicator Table 9: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_JAT Field Name undEn ovrEn Field Type UINT1 UINT1 Field Description Jitter attenuator FIFO underrun detection enable Jitter attenuator FIFO overrun detection enable Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 36 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 10: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_SLIP Field Name slipEn Field Type UINT1 Field Description Elastic store FIFO underrun/overrun detection enable Elastic store FIFO underrun/overrun indicator (1 = overrun, 0 = underrun) slipInd UINT1 Table 11: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_T1FRMR Field Name COFAEn ferEn beeEn sefEn mfpEn mfpInd infrEn infrInd Field Type UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 Field Description Change of frame alignment detection enable Framing bit error detection enable Bit error event detection enable Severely errored frame detection enable Mimic frame pattern detection enable Mimic frame pattern status indicator In frame detection enable In frame status indicator Table 12: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_IBCD Field Name lbaEn lbaInd lbdEn lbdInd Field Type UINT1 UINT1 UINT1 UINT1 Field Description Activate loopback code detection enable Activate loopback code status indicator Deactivate loopback code detection enable Deactivate loopback code status indicator Table 13: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_ALMI Field Name yelEn Field Type UINT1 Field Description Yellow alarm detection enable Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 37 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name yelInd redEn redInd AISEn AISInd Field Type UINT1 UINT1 UINT1 UINT1 UINT1 Field Description Yellow alarm status indicator Red alarm detection enable Red alarm status indicator AIS detection enable AIS status indicator Table 14: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_PDVD Field Name z16dEn pdvdEn pdvdInd Field Type UINT1 UINT1 UINT1 Field Description 16 consecutive zero detection enable Pulse density violation detection enable Pulse density violation status indicator Table 15: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_XPDE Field Name stufEn z16dEn pdvEn pdvInd Field Type UINT1 UINT1 UINT1 UINT1 Field Description Bit stuff detection enable 16 consecutive zero detection enable Pulse density enforcer violation detection enable Pulse density enforcer violation status indicator Table 16: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_RBOC Field Name idleEn BOCEn Field Type UINT1 UINT1 Field Description Idle code detection enable BOC code detection enable Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 38 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 17: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_E1TRAN Field Name sigmfEn nfasEn mfEn smfEn frmEn Field Type UINT1 UINT1 UINT1 UINT1 UINT1 Field Description Signaling multiframe boundary detection enable NFAS frame boundary detection enable CRC-4 multiframe boundary detection enable Signaling multiframe boundary detection enable Frame boundary detection enable Table 18: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_E1FRMR Field Name c2nciwEn Field Type UINT1 Field Description CRC to non-CRC internetworking detection enable CRC to non-CRC internetworking status indicator Out of frame detection enable Out of frame status indicator Out of signaling multiframe detection enable Out of signaling multiframe status indicator Out of CRC-4 multiframe detection enable Out of CRC-4 multiframe status indicator Change of frame alignment detection enable Frame error detection enable Signaling multiframe error detection enable CRC-4 multiframe error detection enable Remote alarm indication detection enable Remote alarm indication status indicator c2nciwInd UINT1 OOFEn OOFInd oosmfEn oosmfInd oocmfEn oocmfInd COFAEn ferEn smferEn cmferEn RAIEn RAIInd UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 39 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name RMAIEn Field Type UINT1 Field Description Remote muliframe alarm indication detect enable Remote multiframe alarm indication status indicator AIS (low zero bit density) detection enable AIS (low zero bit density) status indicator Red alarm detection enable Red alarm status indicator AIS (unframed all ones) detect enable AIS (unframed all ones) status indicator far end block error detection enable CRC error detection enable National bit codeword 4 change detection enable National bit codeword 5 change detection enable National bit codeword 6 change detection enable National bit codeword 7 change detection enable National bit codeword 8 change detection enable Out of offline frame detection enable Out of offline frame status indicator Remote alarm indication and continuous CRC detection enable Remote alarm indication and continuous CRC status indicator RMAIInd UINT1 AISdEn AISdInd redEn redInd AISEn AISInd FEBEEn CRCEn sa4En UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 sa5En UINT1 sa6En UINT1 sa7En UINT1 sa8En UINT1 oOOfEn oOOFInd RAIcCRCEn UINT1 UINT1 UINT1 RAIcCRCInd UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 40 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name cFEBEEn cFEBEInd v52linkEn v52linkInd brfpEn icsmfpEn Field Type UINT1 UINT1 UINT1 UINT1 UINT1 UINT1 Field Description Continuous far end block error detection enable Continuous far end block error status indicator V5.2 link identification detection enable V5.2 link identification status indicator Basic frame boundary interrupt enable CRC-4 sub-multiframe boundary interrupt enable CRC-4 multiframe boundary interrupt enable Signaling multiframe boundary enable icmfpEn ismfpEn UINT1 UINT1 Table 19: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_TDPR Field Name printEn fullEn ovrEn udrEn lfillEn Field Type UINT1 UINT1 UINT1 UINT1 UINT1 Field Description Performance report ready detection enable TDPR FIFO full detection enable TDPR FIFO overrun detection enable TDPR FIFO underrun detection enable TDPR FIFO low level fill threshold detection enable TDPR FIFO full indicator TDPR FIFO below lower threshold indicator fullInd blFillInd UINT1 UINT1 Table 20: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_RDLC Field Name rdlcEn pcktInLastBI nd Field Type UINT1 UINT1 Field Description Receive data link control interrupt enable Last byte of non-aborted packet in FIFO indicator Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 41 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name colsInd fifoOvrInd fifoEmptyInd Field Type UINT1 UINT1 UINT1 Field Description Change of Link Status indicator RDLC FIFO overrun indicator RDLC FIFO empty indicator Table 21: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_PRBS Field Name syncEn Field Type UINT1 Field Description Change in PRBS/PRGD checker state detection enable PRBS/PRGD synchronization state indicator PRBS/PRGD receive bit error detection enable PRBS/PRGD metrics updated detection enable PRBS/PRGD transfer overwrite indicator syncInd beEn xferEn ovrnInd UINT1 UINT1 UINT1 UINT1 Table 22: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_SIGX Field Name COSSEn COSSInd Field Type UINT1 UINT1[32] Field Description Change of signaling state detection enable Change of signaling state per time slot indication Table 23: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_PMON Field Name pmonEn Field Type UINT1 Field Description Performance monitoring transfer interrupt enable Performance monitoring count overrun indication ovrnInd UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 42 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 24: COMET-QUAD ISR SubMask: sCMQ_ISR_MASK_BTIF Field Name parEn speInd dpeInd Field Type UINT1 UINT1 UINT1 Field Description Parity error detection enable Signal parity error indicator Data parity error indicator Other API Structures The following structures are used by the application when executing API functions. The user is encouraged to refer to this section for detailed explanations of the configuration options available in the functions defined in section 4, Application Programming Interface. Interface Configuration API Structures Table 25: COMET-QUAD Transmit Jitter Attenuator Configuration: sCMQ_CFG_TX_JAT Field Name enable refDiv Field Type UINT2 UINT1 Field Description Enables the TJAT or selects TJAT bypass. One less than the ratio between the frequency of the recovered clock and the frequency of the phase discriminator input One less than the ratio between the frequency of the output clock and the frequency of the phase discriminator input Enables the FIFO to self-center the read pointer upon FIFO overrun or underrun Set to prevent FIFO underflows/overflows at the expense of limited jitter attenuation. Selects output clock source: CMQ_TJAT_OUTPUT_CLK_INTERN_JAT, CMQ_TJAT_OUTPUT_CLK_CTCLK, CMQ_TJAT_OUTPUT_CLK_FIFO_INPUT outputDiv UINT1 FIFOselfCenter UINT1 preventOvfUndf UINT1 outputClock eCMQ_TJAT_OUT PUT_CLK_SRC Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 43 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name pllRefClock Field Type eCMQ_TJAT_PLL _REF_CLK_SRC Field Description Selects phase lock loop reference clock source: CMQ_TJAT_PLL_REF_CLK_FIFO_INPUT, CMQ_TJAT_PLL_REF_CLK_BACKPLANE, CMQ_TJAT_PLL_REF_CLK_RECOVERED, CMQ_TJAT_PLL_REF_CLK_CTCLK Table 26: COMET-QUAD Receive Jitter Attenuator Configuration: sCMQ_CFG_RX_JAT Field Name enable refDiv Field Type UINT2 UINT1 Field Description Enables the RJAT or selects RJAT bypass One less than the ratio between the frequency of the recovered clock and the frequency of the phase discriminator input One less than the ratio between the frequency of the output clock and the frequency of the phase discriminator input Enables the FIFO to self-center the read pointer upon FIFO overrun or underrun Set to prevent FIFO underflows/overflows at the expense of limited jitter attenuation outputDiv UINT1 FIFOselfCenter UINT1 preventOvfUndf UINT1 Table 27: COMET-QUAD Receive Clock Configuration: sCMQ_CFG_RX_CLK Field Name recoverClkSel Field Type eCMQ_RX_RECOVER_CLK Field Description Clock recovery algorithm; select between high or low frequency jitter tolerance algorithms: CMQ_RECOVER_CLK_LOW_FREQ_JAT, CMQ_RECOVER_CLK_HIGH_FREQ_JAT Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 44 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name LOSThresh Field Type eCMQ_CDRC_LOS_THRES H Field Description Digital loss of signal threshold in PCM samples: CMQ_LOS_THRESH_PCM_10_HDB3 (E1), CMQ_LOS_THRESH_PCM_15_B8ZS (T1), CMQ_LOS_THRESH_PCM_15_AMI, CMQ_LOS_THRESH_PCM_31, CMQ_LOS_THRESH_PCM_63, CMQ_LOS_THRESH_PCM_175 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 45 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 28: COMET-QUAD Line Side Interface Analog Transmitter Configuration: sCMQ_CFG_TX_ANALOG Field Name txEn Field Type UINT2 Field Description If zero, transmit lines TXTIP and TXRING are held in high impedance state Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 46 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name wvFormType Field Type eCMQ_TX_LBO Field Description Selection of the transmit pulse waveform type and waveform scale factor. Predefined tables are from the COMET and COMET-QUAD data sheet. To specify a user-defined waveform definition and scale factor, this should be set to CMQ_TX_LBO_USER_DEFINED. The user must then specify their own waveform data in wvFormData and their own waveform amplitude scaling factor in wvFormScFac. If this value is CMQ_TX_LBO_RETAIN_CURRENT, no changes are made. Select one of: CMQ_TX_LBO_T1_LONG_HAUL_0DB, CMQ_TX_LBO_T1_LONG_HAUL_7_5DB, CMQ_TX_LBO_T1_LONG_HAUL_15DB, CMQ_TX_LBO_T1_LONG_HAUL_22_5DB, CMQ_TX_LBO_T1_LONG_HAUL_TR62411_0D B CMQ_TX_LBO_T1_SHORT_HAUL_110FT, CMQ_TX_LBO_T1_SHORT_HAUL_220FT, CMQ_TX_LBO_T1_SHORT_HAUL_330FT, CMQ_TX_LBO_T1_SHORT_HAUL_440FT, CMQ_TX_LBO_T1_SHORT_HAUL_550FT, CMQ_TX_LBO_T1_SHORT_HAUL_660FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_1 10FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_2 20FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_3 30FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_4 40FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_5 50FT, CMQ_TX_LBO_T1_SHORT_HAUL_TR62411_6 60FT, CMQ_TX_LBO_E1_75OHM, CMQ_TX_LBO_E1_120OHM, CMQ_TX_LBO_USER_DEFINED, CMQ_TX_LBO_RETAIN_CURRENT Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 47 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name wvFormScFac Field Type UINT1 Field Description Amplitude control of DAC output. Increments are in 11.14 mA. This parameter is only used if wvFormType = CMQ_TX_LBO_USER_DEFINED. A value of 0 tri-states the output line and the max value is 21 (234mA). If the transmit waveform type is not CMQ_TX_LBO_USER_DEFINED, the value corresponding to the specified line build out configuration is applied. wvFormData UINT1[24][5] User defined waveform. 24 7-bit samples of five unit intervals. Select either fuse programming burned into the transmit LIU with CMQ_TX_FUSE_DATA_LIU_FUSE or user defined with CMQ_TX_FUSE_DATA_USER_DEFINED fuseDataSel eCMQ_TX_FUSE_DATA alogTstPosCtrl INT1 Used when fuseDataSel is CMQ_TX_FUSE_DATA_USER_DEFINED. Controls the digital to analog converted positive current control in steps of 0.78125% in either the negative or positive direction. Valid range is -63 to +63. alogTstNegCtrl INT1 Used when fuseDataSel is CMQ_TX_FUSE_DATA_USER_DEFINED. Controls the digital to analog converted negative current control in steps of 0.78125% in either the negative or positive direction. Valid range is -63 to +63. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 48 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 29: COMET-QUAD Analog Receiver Configuration: sCMQ_CFG_RX_ANALOG Field Name aLosThreshold Field Type eCMQ_RX_ALOS_THRESH Field Description Analog loss of signal threshold. Note that the device requires that both the detection and clearance thresholds be the same so this value is applied to both the clearance and detection thresholds. One of: CMQ_RX_ALOS_9DB_THRESH, CMQ_RX_ALOS_14_5DB_THRESH, CMQ_RX_ALOS_20DB_THRESH, CMQ_RX_ALOS_22DB_THRESH, CMQ_RX_ALOS_25DB_THRESH, CMQ_RX_ALOS_30DB_THRESH, CMQ_RX_ALOS_31DB_THRESH, CMQ_RX_ALOS_35DB_THRESH aLosDetectPeriod UINT1 Duration for declaring analog loss of signal. The actual duration used is 16 x aLosDetectPeriod pulse intervals Duration for clearing analog loss of signal. The actual duration used is 16 x aLosClearPeriod pulse intervals aLosClearPeriod UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 49 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name eqFreq Field Type eCMQ_RX_ALOG_EQ_FREQ Field Description Equalizer feedback loop frequency. One of: CMQ_RX_EQ_FREQ_T1_24_125KHZ (24.125 kHz), CMQ_RX_EQ_FREQ_T1_12_063KHZ (12.063 kHz), CMQ_RX_EQ_FREQ_T1_8_0417KHZ (8.0417 kHz), CMQ_RX_EQ_FREQ_T1_6_0313KHZ (6.0313 kHz), CMQ_RX_EQ_FREQ_T1_4_8250KHZ (4.8250 kHz), CMQ_RX_EQ_FREQ_T1_4_0208KHZ (4.0208 kHz), CMQ_RX_EQ_FREQ_T1_3_4464KHZ (3.4464 kHz), CMQ_RX_EQ_FREQ_T1_3_0156KHZ (3.0156 kHz), CMQ_RX_EQ_FREQ_E1_32_000KHZ (32.000 kHz), CMQ_RX_EQ_FREQ_E1_16_000KHZ (16.000 kHz), CMQ_RX_EQ_FREQ_E1_10_667KHZ (10.667 kHz), CMQ_RX_EQ_FREQ_E1_8_000KHZ (8.000 kHz), CMQ_RX_EQ_FREQ_E1_6_40KHZ (6.40 kHz), CMQ_RX_EQ_FREQ_E1_5_333KHZ (5.333 kHz), CMQ_RX_EQ_FREQ_E1_4_5714KHZ (4.5714 kHz), CMQ_RX_EQ_FREQ_E1_4_0KHZ (4.0 kHz) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 50 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name eqFdBckPer Field Type eCMQ_RX_ALOG_EQ_PER Field Description Specifies the time interval that the equalizer dB counter must be stable before declaring stable equalization state. The period is based on equalizer feedback loop frequency. One of: CMQ_RX_EQ_VALID_PERIOD_32, CMQ_RX_EQ_VALID_PERIOD_64, CMQ_RX_EQ_VALID_PERIOD_128 CMQ_RX_EQ_VALID_PERIOD_256 ramType eCMQ_RX_LINE_EQ Selects either user defined receiver equalizer RAM in eqCoef, a predefined equalizer RAM from the COMET and COMET-QUAD data sheet, or no change to the equalizer settings: CMQ_RX_LINE_EQ_RAM_T1, CMQ_RX_LINE_EQ_RAM_E1, CMQ_RX_LINE_EQ_USER_DEFINED, CMQ_RX_LINE_EQ_RETAIN_CURRENT eqCoef UINT4[256] Programmable equalizer coefficients. If ramType is CMQ_RX_LINE_EQ_USER_DEFINED, this array should contain the new coefficients. squelchEn UINT1 Enable/disable data squelching (force data to all 0's) upon analog loss of signal detection Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 51 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 30: COMET-QUAD Backplane Access Configuration: sCMQ_BACKPLANE_ACCESS_CFG Field Name masterMode dataMode Field Type UINT1 eCMQ_BACKPLAN E_DATA_MODE Field Description Selects slave or master backplane mode Data format mode. Only used if masterMode is set (clock master), otherwise ignored. Select one of: CMQ_BACKPLANE_FULL_FRAME_MODE, CMQ_BACKPLANE_NX56K_MODE, CMQ_BACKPLANE_NX64K_MODE, CMQ_BACKPLANE_NX64K_E1_MODE, clkTimes2 UINT1 Select clock mode multiplication by two. If set, clock operates at twice the backplane rate. The backplane data rate. Should be one of: CMQ_BACKPLANE_CLK_RATE_1544, CMQ_BACKPLANE_CLK_RATE_2048, CMQ_BACKPLANE_CLK_RATE_8192, dataRate eCMQ_BACKPLAN E_DATA_RATE Table 31: COMET-QUAD Backplane Receive Frame Configuration: sCMQ_CFG_BRIF_FRM Field Name fpMaster fpmMode Field Type UINT1 eCMQ_BACKPLANE_ RX_FRAMEPULSE_M ODE Field Description Selects frame pulse signal master/slave Configure the type of frame pulse transmitted on the backplane. Only used if frame pulse is master. Should be one of: CMQ_BACKPLANE_RX_FP_T1_HIGH_ON_SF_ESF, CMQ_BACKPLANE_RX_FP_T1E1_HIGH_EVERY_FRAME, CMQ_BACKPLANE_RX_FP_E1_HIGH_ON_CRC_MFRM, CMQ_BACKPLANE_RX_FP_E1_HIGH_ON_SIG_MFRM, CMQ_BACKPLANE_RX_FP_E1_COMP_MFRM , CMQ_BACKPLANE_RX_FP_E1_HIGH_ON_OVERHEAD fpInvEn parInsEn oddPar UINT1 UINT1 UINT1 Enable inversion of the frame pulse signal Enable parity insertion Odd/even parity selection. Only used if parity insertion enabled Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 52 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name extParEn Field Type UINT1 Field Description Enable extension of parity over current and previous frame Enable fixing of F bit, only valid when not in parity insertion mode Polarity of the F bit, valid only when fBitFix is 1 and not in parity mode Offset in bytes between the framing pulse and start of next frame: valid range: 0 - 127 bytes Enables offset between frame pulse and first timeslot in bits If bit offset is enabled, this value will be applied as the bit offset between the frame pulse and the first timeslot. This field should be a 3 bit value. Enabling this option causes the framing bit to contain FDL data. Only supported for T1 ESF frame formats Selects timeslot mapping format when mapping a 1.544 MHz line onto a 2.048 MHz backplane. If this timeslot translation is not required (i.e. when the line rate matches the backplane rate) this value is ignored Should be one of: CMQ_BACKPLANE_TIMESLOT_MAP_3_OF_4, CMQ_BACKPLANE_TIMESLOT_MAP_24_OF_32 fBitFix UINT1 fBitPol UINT1 fpFrmOff set fpBitOff setEn fpBitOff set UINT1 UINT1 UINT1 altFDLEn UINT1 tslotMap Format eCMQ_BACKPLANE_ TIMESLOT_MAP Table 32: COMET-QUAD Backplane Transmit Frame Configuration: sCMQ_CFG_BTIF_FRM Field Name fpMaster fpInvEn oddPar extParEn Field Type UINT1 UINT1 UINT1 UINT1 Field Description Selects frame pulse signal master/slave Enable inversion of the frame pulse signal Odd/even parity selection Enable extension of parity over current and previous frame Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 53 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name fpFrmOffset Field Type UINT1 Field Description Offset in bytes between the framing pulse and start of next frame: valid range: 0 - 127 bytes For T1 mode, enables ESF alignment as opposed to SF alignment. This option is not supported for E1 mode Enables offset between frame pulse and first timeslot in bits If bit offset is enabled, this value will be applied as the bit offset between the frame pulse and the first timeslot (3 bit value) Selects timeslot mapping format when mapping 2.048 MHz backplane onto 1.544 MHz line. If this timeslot translation is not required (i.e., when the line rate matches the backplane rate), this value is ignored. Should be one of: CMQ_BACKPLANE_TIMESLOT_MAP_3_OF_4 CMQ_BACKPLANE_TIMESLOT_MAP_24_OF_32 T1ESFAlign UINT1 fpBitOffsetEn UINT1 fpBitOffset UINT1 tslotMapFormat eCMQ_BACKP LANE_TIMES LOT_MAP Table 33: COMET-QUAD H-MVIP Configuration: sCMQ_CFG_HMVIP Field Name rxHMVIPMode Field Type eCMQ_BACKPLANE_ HMVIP_MODE Field Description Enable HMVIP, enable CCS, or disable both on the receive backplane interface. Should be one of: CMQ_BACKPLANE_HMVIP_MODE, CMQ_BACKPLANE_HMVIP_CCS, CMQ_BACKPLANE_HMVIP_DISABLE txHMVIPMode eCMQ_BACKPLANE_ HMVIP_MODE Enable HMVIP, enable CCS, or disable both on the transmit backplane interface. Should be one of: CMQ_BACKPLANE_HMVIP_MODE, CMQ_BACKPLANE_HMVIP_CCS, CMQ_BACKPLANE_HMVIP_DISABLE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 54 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name txEnableCCS InTs15 Field Type UINT1[4] Field Description Selects whether or not common channel signaling from the transmit backplane interface is inserted into timeslot 15. Only used when E1 mode and txHMVIPMode is set for CCS Selects whether or not common channel signaling from the transmit backplane interface is inserted into timeslot 16. Only used when E1 mode and txHMVIPMode is set for CCS Selects whether or not common channel signaling from the transmit backplane interface is inserted into timeslot 31. Only used when E1 mode and txHMVIPMode is set for CCS txEnableCCS InTs16 UINT1[4] txEnableCCS InTs31 UINT1[4] Table 34: COMET-QUAD Receive Elastic Store Configuration: sCMQ_CFG_RX_ELST Field Name elstEnable idleCode CCSidleCode Field Type UINT1 UINT1 UINT1 Field Description Enable/disable the elastic store Elastic store idle code Elastic store CCS idle code (Comet-Quad only) T1/E1 Framers API Structures Table 35: COMET-QUAD T1 Transmit Framer Configuration: sCMQ_CFG_T1TX_FRM Field Name frmMode Field Type eCMQ_FRAME_MODE Field Description T1 transmit framing format. Should be one of: CMQ_FRM_MODE_T1_SF, CMQ_FRM_MODE_T1_DM, CMQ_FRM_MODE_T1_SLC96, CMQ_FRM_MODE_T1_DM_FDL, CMQ_FRM_MODE_T1_ESF, CMQ_FRM_MODE_T1_SF_JPN_ALARM, CMQ_FRM_MODE_T1_DM_JPN_ALARM, CMQ_FRM_MODE_T1_SLC96_JPN_ALARM, CMQ_FRM_MODE_T1_DM_FDL_JPN_ALARM, CMQ_FRM_MODE_T1_JT_G704, CMQ_FRM_MODE_T1_UNFRAMED Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 55 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name zSupFormat Field Type eCMQ_T1_ZSUP_FOR MAT Field Description Zero code suppression format to be used. Should be one of: CMQ_T1_ZSUP_NONE, CMQ_T1_ZSUP_DDS, CMQ_T1_ZSUP_GTE, CMQ_T1_ZSUP_BELL SFSigAlignerEn UINT1 Enables the signaling aligner to ensure that signaling alignment between superframes on the backplane and the transmit framer is maintained. Note that when using this option, the ESF alignment option in the transmit backplane frame pulse configuration must be off. Table 36: COMET-QUAD T1 Receive Framer Configuration: sCMQ_CFG_T1RX_FRM Field Name frmMode Field Type eCMQ_FRAME_MO DE Field Description T1 receive framing format. Should be one of: CMQ_FRM_MODE_T1_SF, CMQ_FRM_MODE_T1_DM, CMQ_FRM_MODE_T1_SLC96, CMQ_FRM_MODE_T1_DM_FDL, CMQ_FRM_MODE_T1_ESF, CMQ_FRM_MODE_T1_SF_JPN_ALARM, CMQ_FRM_MODE_T1_DM_JPN_ALARM, CMQ_FRM_MODE_T1_SLC96_JPN_ALARM, CMQ_FRM_MODE_T1_DM_FDL_JPN_ALARM, CMQ_FRM_MODE_T1_JT_G704, CMQ_FRM_MODE_T1_UNFRAMED outOfFrameCriteria eCMQ_T1_FRAME _LOSS_THRESH Selects criteria for declaring out of frame. Note that if frmMode is T1DM, this parameter has no effect as the criteria is fixed at 4 out of 12. Select one of: CMQ_T1_OOF_2OF4, CMQ_T1_OOF_2OF5, CMQ_T1_OOF_2OF6 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 56 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name frmESFAlgo Field Type eCMQ_T1_ESF_F RAME_ALGO Field Description For ESF framing formats, this parameter selects whether to use the ESF frame alignment algorithm based on a continuous CRC-6 calculation or the ESF frame alignment algorithm where frame alignment is not declared while there are two framing candidates. Select one of CMQ_T1_ESF_FRAME_ALGO_ONE_CANDIDAT E or CMQ_T1_ESF_FRAME_ALGO_CRC_6 COFACntEn UINT1 Enable counting of change of frame alignment (COFA) events rather than out of frame alignment (OOF) events in the PMON Table 37: COMET-QUAD E1 Transmit Framer Configuration: sCMQ_CFG_E1TX_FRM Field Name frmMode Field Type eCMQ_FRAME_MODE Field Description E1 transmit framing format. Should be one of: CMQ_FRM_MODE_E1, CMQ_FRM_MODE_E1_CRC_MFRM, CMQ_FRM_MODE_E1_UNFRAMED ts16Signaling eCMQ_E1_SIG_INSE RTION Type of signaling to insert into timeslot 16. Select from: CMQ_E1_SIG_INS_NONE, CMQ_E1_SIG_INS_HDLC_CCS, CMQ_E1_SIG_INS_CAS insNatIntBitEn UINT1 Enables insertion of international and national bits into timeslot 0 of NFAS frames Enables insertion of extra bits into timeslot 16 of frame 0 in a signaling multiframe If CRC multiframe mode selected, this value enables insertion of far end block error (FEBE) bits. insXtraBitsEn UINT1 insFEBEEn UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 57 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Table 38: COMET-QUAD E1 Receive Framer Configuration: sCMQ_CFG_E1RX_FRM Field Name frmMode Field Type eCMQ_FRAME_ MODE Field Description E1 transmit framing format. Should be one of: CMQ_FRM_MODE_E1, CMQ_FRM_MODE_E1_CRC_MFRM, CMQ_FRM_MODE_E1_UNFRAMED CASAlignmentEn UINT1 Enable alignment to channel associative signaling multiframes Enable checking of CRC multiframe in CRC to non-CRC internetworking mode Disable reframing upon any error event Enable a forced reframe to occur when excessive CRC errors are reported Enable loss of frame criteria: Bit 2, timeslot 0 of NFAS frames is 0 in 3 consecutive frames Enable errors in bit 2 of timeslot 0 of NFAS frames to contribute towards the framing error count Enable multiple FAS errors to generate a single framing error. If NFAS errors are counted towards framing errors, enabling this option includes Bit 2 of timeslot 0 in NFAS frames as part of the FAS word CRC2NCRCEn UINT1 noReframeOnErrEn reframeOnXSCrcErrEn UINT1 UINT1 lofBit2CritEn UINT1 NFASErrEn UINT1 multFASEOneFEEn UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 58 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name mfrmLossAlignCrit Field Type eCMQ_E1_LOS S_MFRM_ALIG N_TS16_CRIT Field Description Select additional timeslot 16 criteria for declaring loss of signaling mutliframe alignment of either all 0's in timeslot 16 for 1 or 2 multiframes. Note that the selection made here is in addition to the criteria of 2 consecutive mutliframe alignment pattern errors which always generates a loss of signaling multiframe alignment declaration Select from: CMQ_E1_LOSS_MFRM_ALIGN_TS16_CRIT_NO NE, CMQ_E1_LOSS_MFRM_ALIGN_TS16_CRIT_ZE RO_1_MFRM, CMQ_E1_LOSS_MFRM_ALIGN_TS16_CRIT_ZE RO_2_MFRM AISCriteria eCMQ_E1_AIS _CRIT Criteria for declaring AIS. Select between less than 3 zeroes in 512 consecutive bits or 2 consecutive periods of less than 3 zeroes in 512 consecutive bits: CMQ_E1_AIS_CRIT_3Z_IN_512BITs CMQ_E1_AIS_CRIT_2_PERIODS_3Z_IN_512 BITS RAICriteria eCMQ_E1_RAI _CRIT Criteria for declaring RAI. Select between declaration upon receiving any A-bit (bit 3, timeslot 0) that is 1 or declaration upon four consecutive A-bits that are one CMQ_E1_RAI_CRIT_ALL_A_1, CMQ_E1_RAI_CRIT_4_CONSEC_A_1 Alarm Control and Inband Communications API Structures Table 39: COMET-QUAD HDLC Link Extraction/Insertion Location Configuration: sCMQ_CFG_HDLC_LINK Field Name useT1DataLink Field Type UINT1 Field Description Specifies the use of the T1 FDL (ESF or T1DM with FDL modes). For COMET, only valid for first HDLC controller. In E1 mode, this value should be 0 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 59 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name evenFrames Field Type UINT1 Field Description Enable link extraction/insertion from even frames. Ignored when using T1 data link Enable link extraction/insertion from odd frames. Ignored when using T1 data link Timeslot to extract data link from (0 based). Ignored if both oddFrames and evenFrames are 0 or if using T1 data link Bit mask selecting which of the bits in a timeslot/channel are to be used. Ignored if both oddFrames and evenFrames are 0 or if using T1 Data Link oddFrames UINT1 timeslot UINT1 dataLinkBitMask UINT1 Table 40: COMET-QUAD HDLC Receiver Configuration: sCMQ_CFG_HDLC_RX Field Name linkLocation Field Type sCMQ_CFG_HDLC _LINK UINT1 Field Description Specifies where to extract the HDLC link from Forces detection of packets with either an address of all 1's or an address matching either the primary or secondary addresses Specifies the receive HDLC controller to ignore the two least significant bits of the primary and secondary addresses when looking for matches addrMatchEn addrMaskEn UINT1 Table 41: COMET-QUAD HDLC Receiver Configuration: sCMQ_CFG_HDLC_TX Field Name linkLocation Field Type sCMQ_CFG_H DLC_LINK UINT1 UINT1 UINT1 Field Description Specifies where to insert the HDLC link Enables sharing of start/end flags between packets Enables CRC frame check sequence generation Enables performance report transmission. For COMET devices, this option is valid only for the first HDLC controller. flagShareEn crcFCSEn pmRepEn Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 60 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Status and Statistics API Structures Table 42: COMET-QUAD Clock Status Structure: sCMQ_CLK_STATUS Field Name XCLCKactive Field Type UINT1 Field Description Indicates XCLK is alive. Note that this value on COMET-QUAD devices is not quadrant based. Indicates BTCLK is alive Indicates CTCLK is alive Indicates BRCLK is alive Indicates RCLKI is alive Indicates CSU has locked onto XCLK. Note that this value on COMET-QUAD devices is not quadrant based. BTCLKactive CTCLKactive BRCLKactive RCLKIactive CSULock UINT1 UINT1 UINT1 UINT1 UINT1 Table 43: COMET-QUAD Framer Statistics: sCMQ_FRM_CNTS Field Name frmErrCnt T1_OOF_COFA_Cnt Field Type UINT1[4] UINT4[4] Field Description Framing error count (T1 and E1) Out of frame count or change of frame alignment count depending on option selected for T1 receive framer E1 Far end block error count T1 bit error event count E1 CRC error count Line code violation count (T1 and E1) E1_FEBECnt T1_BitErrCnt E1_CRCErrCnt lcvCnt UINT2[4] UINT4[4] UINT2[4] UINT4[4] Table 44: COMET-QUAD Framer Status: sCMQ_FRM_STATUS Field Name lossOfSignal lossOfFrame Field Type UINT1[4] UINT1[4] Field Description Loss of signal indicator Loss of frame alignment indicator Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 61 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name AIS yelAlm E1_lossOfSMF Field Type UINT1[4] UINT1[4] UINT1[4] Field Description AIS alarm indicator Yellow alarm (E1 RAI) indicator E1 loss of signaling multiframe alignment indicator (unused for T1) E1 loss of CRC-4 multiframe alignment indicator (unused for T1) E1 timeslot 16 RAI alarm indicator (unused for T1) E1_lossOfCMF UINT1[4] E1_ts16RAI UINT1[4] Table 45: COMET-QUAD T1 Automatic Performance Monitoring Message: sCMQ_STAT_APRM Field Name octet2 Field Type UINT1 Field Description Service access point identifier, command response flag, extended address flag Terminal endpoint identifier, extended address2 flag Performance report control field Event threshold flags: see data sheet Event threshold flags: see data sheet octet3 UINT1 octet4 octet5 octet6 UINT1 UINT1 UINT1 3.3 Structures in the Driver's Allocated Memory These structures are defined and used by the driver and are part of the context memory allocated when the driver is opened. These structures are the Module Data Block (MDB) and the Device Data Block (DDB). Module Data Block: MDB The MDB is the top-level structure for the module. It contains configuration data about the module level code and pointers to configuration data about the device level codes. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 62 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures * errModule indicates specific error codes returned by API functions that are not passed directly to the application. Most of the module API functions return a specific error code directly. When the returned code is not CMQ_SUCCESS, this indicates that the top-level function was not able to carry the specified error code back to the application. Under those circumstances, the proper error code is recorded in this element. The element is the first in the structure so that the USER can cast the MDB pointer into an INT4 pointer and retrieve the local error. This eliminates the need to include the MDB template into the application code valid indicates that this structure has been properly initialized and may be read by the * * USER stateModule contains the current state of the module and can be any one of: CMQ_MOD_START, CMQ_MOD_IDLE or CMQ_MOD_READY Table 46: COMET-QUAD Module Data Block: sCMQ_MDB Field Name errModule valid Field Type INT4 UINT2 Field Description Global error indicator for module calls Indicates that this structure has been initialized Module state; can be any one of the following: CMQ_MOD_START, CMQ_MOD_IDLE or CMQ_MOD_READY Maximum number of devices supported Number of devices currently registered Maximum number of initialization profiles (array of) Device Data Blocks (DDB) in context memory (array of) Initialization profiles in context memory stateModule eCMQ_MOD_STATE maxDevs numDevs maxInitProfs pddb UINT2 UINT2 UINT2 sCMQ_DDB * pinitProfs sCMQ_DIV * Device Data Block: DDB The DDB is the top-level structure for each device. It contains configuration data about the device level code and pointers to configuration data about device level sub-blocks. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 63 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures * errDevice indicates specific error codes returned by API functions that are not passed directly to the application. Most of the device API functions return a specific error code directly. When the returned code is CMQ_FAILURE, this indicates that the top-level function is not able to carry the specified error code back to the application. In addition, some device functions do not return an error code. Under those circumstances, the proper error code is recorded in this element. This element is the first in the structure so that the USER can cast the DDB pointer to an INT4 pointer and retrieve the local error. This eliminates the need to include the DDB template in the application code valid indicates that this structure has been properly initialized and may be read by the * * * USER stateDevice contains the current state of the device and can be any one of: CMQ_START, CMQ_PRESENT, CMQ_ACTIVE or CMQ_INACTIVE usrCtxt is a value that can be used by the USER to identify the device during the execution of the callback functions. It is passed to the driver when cometqAdd is called and returned to the USER when a callback function is invoked Table 47: COMET-QUAD Device Data Block: sCMQ_DDB Field Name errDevice valid Field Type INT4 UINT2 Field Description Global error indicator for device calls Indicates that this structure has been initialized Device State; can be one of the following: CMQ_PRESENT, CMQ_ACTIVE or CMQ_INACTIVE Base address of the Device Stores the user's context for the device. It is passed as an input parameter when the driver invokes an application callback Profile number used at initialization Indicates the current mode of interrupt processing Address for the callback function for Framer Events Address for the callback function for Line Side Interface Events stateDevice CMQ_DEV_STATE baseAddr usrCtxt UINT1 * void * profileNum pollISR UINT2 sCMQ_POLL cbackFramer CMQ_CBACK cbackIntf CMQ_CBACK Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 64 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name cbackAlarmInBand Field Type CMQ_CBACK Field Description Address for the callback function for Alarm InBand Events Address for the callback function for Signal Insertion and Extraction Events Address for the callback function for Performance Monitoring Events Address for the callback function for Serial Control Events Indicates the device type: COMET (= 0) or COMET-QUAD (= 1) Operational mode of the device. A one indicates E1 mode and a value of zero indicates T1 mode Interrupt enable mask cbackSigInsExt CMQ_CBACK cbackPMon CMQ_CBACK cbackSerialCtl CMQ_CBACK cometqFlag UINT1 modeE1 UINT1 mask sCMQ_ISR_MASK 3.4 Structures Passed through RTOS Buffers Interrupt Service Vector: ISV This buffer structure is used to capture the status of the device (during a poll or ISR processing) for use by the Deferred Processing Routine (DPR). It is the application's responsibility to create a pool of ISV buffers (using this template to determine the buffer's size) when the driver calls the user-supplied sysCometqBufferStart function. An individual ISV buffer is then obtained by the driver via sysCometqISVBufferGet and returned to the `pool' via sysCometqISVBufferRtn. Table 48: COMET-QUAD Interrupt Service Vector: sCMQ_ISV Field Name deviceHandle mask Field Type sCMQ_HNDL sCMQ_ISR_MASK Field Description Handle to the device generating interrupts ISR mask with interrupt status information Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 65 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Deferred Processing Vector: DPV This structure is used in two ways. First, it is used to determine the size of the buffer required by the RTOS for use in the driver. Second, it defines the format of the data that is assembled by the DPR and sent to the application code. Note: the application code is responsible for returning this buffer to the RTOS buffer pool. The DPR reports events to the application using user-defined callbacks. The DPR uses each callback to report a functionally-related group of events. Refer to section 4.13 for a description of the COMET and COMET-QUAD callback functions, and to Appendix C for a list of events and bit masks used in the interpretation of the DPV. Within the callback there are three event fields. The callback routine can determine what events are being passed by the DPR by examining the bits in these fields. Appendix C provides a listing of the bit masks required to interpret the bits in the event fields. In addition to the three event fields, the DPR also contains fields that hold additional information that is relevant only when the corresponding event has occurred. For all interrupts that are processed by the DPR simultaneously, only a single invocation of the relevant callback functions takes place. For the multiple framers on a COMET-QUAD device, there is a single callback for all framers. The framer number can be identified by the index into the event fields for which an event bit is set. For COMET devices, only the first element of the arrays in the DPV are used. Table 49: COMET-QUAD Deferred Processing Vector: sCMQ_DPV Field Name event1 event2 event3 CDRCLosInd Field Type UINT4[4] UINT4[4] UINT4[4] UINT1[4] Field Description Event indicator bit field Event indicator bit field Event indicator bit field CDRC loss of signal status indicator. Used with event CMQ_EVENT_CDRC_LOS. CDRC alternate loss of signal status indicator. Used with event CMQ_EVENT_CDRC_ALT_LOS. RLPS analog loss of signal status indicator. Used with event CMQ_EVENT_RLPS_ALOS. T1-FRMR mimic frame pattern status indicator. Used with event CMQ_EVENT_T1_FRMR_MIMIC_FRM. CDRCAltLosInd UINT1[4] RLPSLosInd UINT1[4] T1FRMRMfpInd UINT1[4] Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 66 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name T1FRMRInfrInd Field Type UINT1[4] Field Description T1-FRMR in frame status indicator. Used with event CMQ_EVENT_T1_FRMR_INFRM. IBCDLbaInd UINT1[4] Activate loopback code status indicator. Used with event CMQ_EVENT_IBCD_LPBCK_ACT_CODE. Deactivate loopback code status indicator. Used with event CMQ_EVENT_IBCD_LPBCK_DEACT_CODE. IBCDLbdInd UINT1[4] ALMIYelInd UINT1[4] ALMI yellow alarm status indicator. Used with event CMQ_EVENT_ALMI_YELLOW_ALARM. ALMI red alarm status indicator. Used with event CMQ_EVENT_ALMI_RED_ALARM. ALMIRedInd UINT1[4] ALMIAISInd UINT1[4] ALMI AIS status indicator. Used with event CMQ_EVENT_ALMI_AIS_ALARM. PDVDPdvInd UINT1[4] PDVD pulse density violation status indicator. Used with event CMQ_EVENT_PDVD_PULSE_DENSITY_VIOLT. XPDEPdvInd UINT1[4] XPDE pulse density enforcer violation status indicator. Used with event CMQ_EVENT_XPDE_PULSE_DENSITY_VIOLT. PRBSSyncInd UINT1[4] PRBS/PRGD synchronization state indicator. Used with event CMQ_EVENT_PRBS_PAT_SYNC. PRBS/PRGD transfer overwrite indicator. Used with event CMQ_EVENT_PRBS_XFER_UPD. E1-FRMR CRC to non-CRC internetworking status indicator. Used with event CMQ_EVENT_E1_FRMR_CRC2NCRC. PRBSOvrnInd UINT1[4] E1FRMRC2nciwInd UINT1[4] E1FRMROOFInd UINT1[4] E1-FRMR out of frame status indicator. Used with event CMQ_EVENT_E1_FRMR_OOF. E1-FRMR out of signaling multiframe status indicator. Used with event CMQ_EVENT_E1_FRMR_OOF_SMFRM. E1FRMOOSMFInd UINT1[4] Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 67 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name E1FRMOOCMFInd Field Type UINT1[4] Field Description E1-FRMR out of CRC-4 multiframe status indicator. Used with event CMQ_EVENT_E1_FRMR_OOF_CRC_MFRM. E1FRMOoofInd UINT1[4] E1-FRMR out of offline frame status indicator. Used with event CMQ_EVENT_E1_FRMR_OOF_ALARM. E1FRMRaiCrcInd UINT1[4] E1-FRMR remote alarm indication and continuous CRC status indicator. Used with event CMQ_EVENT_E1_FRMR_RAI_CONT_CRC_ALARM. E1FRMCfebeInd UINT1[4] E1-FRMR far end block error status indicator. Used with event CMQ_EVENT_E1_FRMR_CONT_FEBE_ALARM. E1FRMV52LinkInd UINT1[4] E1-FRMR V5.2 link identification status indicator. Used with event CMQ_EVENT_E1_FRMR_V52LINKID_ALARM. E1FRMRaiInd UINT1[4] E1-FRMR remote alarm indication status indicator. Used with event CMQ_EVENT_E1_FRMR_RAI_ALARM. E1FRMRmaiInd UINT1[4] E1-FRMR remote multiframe alarm indication status indicator. Used with event CMQ_EVENT_E1_FRMR_RMAI_ALARM. E1FRMAisdInd UINT1[4] E1-FRMR AIS (low zero bit density) status indicator. Used with event CMQ_EVENT_E1_FRMR_AISD_ALARM. E1FRMRedInd UINT1[4] E1-FRMR red alarm status indicator. Used with event CMQ_EVENT_E1_FRMR_RED_ALARM. E1-FRMR AIS (unframed all ones) status indicator. Used with event CMQ_EVENT_E1_FRMR_AIS_ALARM. E1FRMAisInd UINT1[4] COSStimeslot UINT4[4] Change of signaling state information bitmap. For E1, bit 0 represents timeslot 0 and bit 31 represents timeslot 31. For T1, bit 1 represents channel 1 and bit 24 represents channel 24. Used with event CMQ_EVENT_SIGX_COS_STATE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 68 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Data Structures Field Name RDLCCOLS Field Type UINT1[4] Field Description RDLC change of link state. Used with event CMQ_EVENT_RDLC_EVENT RDLCPacketIn UINT1[4] RDLC packet indicator. Used with event CMQ_EVENT_RDLC_EVENT RDLCFIFOOvr UINT1[4] RDLC FIFO overrun indicator. Used with event CMQ_EVENT_RDLC_EVENT RDLCFIFOEmpty UINT1[4] RDLC FIFO underrun indicator. Used with event CMQ_EVENT_RDLC_EVENT TDPRFIFOBelowThre sh UINT1[4] TDPR FIFO below threshold indicator. Used with event CMQ_EVENT_TDPR_FIFO_FILL_LOWLVL_THRESH TDPRFIFOFull UINT1[4] TDPR FIFO full indicator. Used with event CMQ_EVENT_TDPR_FIFO_FULL 3.5 Global Variable Although most of the variables within the driver are not intended for used by the application code, there is one global variable that can be of great use to the application code. This variable is called cometqMdb and it acts as a global pointer to the Module Data Block (MDB). The content of this global variable should be considered read-only by the application. * errModule: This structure element is used to store an error code that specifies the reason for an API function's failure. The field is only valid for functions that do not return an error code or when a value of CMQ_FAILURE is returned. stateModule: This structure element is used to store the module state (as shown in Figure * * 3). pddb[ ]: An array of pointers to the individual Device Data Blocks. The USER is cautioned that a DDB is only valid if the valid flag is set. Note that the array of DDBs is in no particular order. errDevice: This structure element is used to store an error code that specifies the reason for an API function's failure. The field is only valid for functions that do not return an error code or when a value of CMQ_FAILURE is returned. stateDevice: This structure element is used to store the device state (as shown in Figure 3). Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 69 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface 4 APPLICATION PROGRAMMING INTERFACE This section of the manual provides a detailed description of each function that is a member of the COMET-QUAD driver Application Programming Interface (API). API functions typically execute in the context of an application task. It is important to note that these functions are not re-entrant. This means that two application tasks can not invoke the same API at the same time. However the driver protects its data structures from concurrent accesses by the Application and the DPR task. 4.1 Module Management The module management is a set of API functions that are used by the Application to open, start, stop and close the driver module. These functions initialize the driver; they also allocate memory and all the RTOS resources needed by the driver. They are also used to change the module state. For more information on the module states see the state diagram on page 21. For a typical module management flow diagram see page 23. All module management functions are device independent, and thus have the same behavior irrespective of whether the driver is being used with COMET-QUAD or COMET devices. Opening the Driver Module: cometqModuleOpen This performs module level initialization of the device driver, which involves allocating all of the memory needed by the driver and initializing the internal structures. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqModuleOpen(sCMQ_MIV *pmiv) pmiv : (pointer to) Module Initialization Vector Places the address of the MDB into the MIV passed by the Application Success = CMQ_SUCCESS Failure = CMQ_MOD_START Changes the MODULE state to CMQ_MOD_IDLE Closing the Driver Module: cometqModuleClose Performs module level shutdown of the driver. This involves deleting all devices being controlled by the driver (by calling cometqDelete for each device) and de-allocating all the memory allocated by the Driver. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 70 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqModuleClose(void) None None Success = CMQ_SUCCESS Failure = Starting the Driver Module: cometqModuleStart Connects the RTOS resources to the Driver. This involves allocating semaphores and timers, initializing buffers, and installing the ISR handler and DPR task. Upon successful return from this function, the driver is ready to add devices. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqModuleStart(void) None None Success = CMQ_SUCCESS Failure = CMQ_MOD_IDLE Changes the MODULE state to CMQ_MOD_READY Stopping the Driver Module: cometqModuleStop Disconnects the RTOS resources from the Driver. This involves de-allocating semaphores and timers, freeing-up buffers, and uninstalling the ISR handler and the DPR task. If there are any registered devices, cometqDelete is called for each. Prototype Inputs Outputs Returns Valid States INT4 cometqModuleStop(void) None None Success = CMQ_SUCCESS Failure = CMQ_MOD_READY Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 71 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Side Effects Changes the MODULE state to CMQ_MOD_IDLE 4.2 Profile Management This section of the manual describes the functions that add, get and clear an initialization profile. Initialization profiles allow the user to store pre-defined Device Initialization Vectors (DIV) that are validated ahead of time. When the device initialization function is invoked only a profile number need be passed. This method simplifies and expedites the initialization process. Adding an Initialization Profile: cometqAddInitProfile Creates an initialization profile that is stored by the driver. A device can now be initialized by simply passing the initialization profile number. Prototype Inputs INT4 cometqAddInitProfile(sCMQ_DIV *pProfile, UINT2 *pProfileNum) pProfile pProfileNum : (pointer to) initialization profile being added : (pointer to) profile number to be assigned by the driver : profile number assigned by the driver Outputs Returns Valid States Side Effects pProfileNum Success = CMQ_SUCCESS Failure = CMQ_MOD_IDLE, CMQ_MOD_READY None Getting an Initialization Profile: cometqGetInitProfile Gets the content of an initialization profile given its profile number. Prototype Inputs Outputs Returns Valid States INT4 cometqGetInitProfile(UINT2 profileNum, sCMQ_DIV *pProfile) profileNum pProfile pProfile : initialization profile number : (pointer to) initialization profile : contents of the corresponding profile Success = CMQ_SUCCESS Failure = CMQ_MOD_IDLE, CMQ_MOD_READY Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 72 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Side Effects None Deleting an Initialization Profile: cometqDeleteInitProfile Deletes an initialization profile given its profile number. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqDeleteInitProfile(UINT2 profileNum) profileNum : initialization profile number None Success = CMQ_SUCCESS Failure = CMQ_MOD_IDLE, CMQ_MOD_READY None 4.3 Device Management The device management is a set of API functions that are used by the Application to control the device. These functions take care of initializing a device in a specific configuration, enabling the device's general activity as well as enabling interrupt processing for that device. They are also used to change the software state for that device. For more information on the device states see the state diagram on page 21. For a typical device management flow diagram see page 24. Adding a Device: cometqAdd This function verifies the presence of a new device in the hardware, then returns a handle back to the user. The device handle is passed as a parameter to most of the Device API Functions. It is used by the driver to identify the device on which the operation is to be performed. When a COMET or COMET-QUAD device is added to the module, the TYPE field in the Revision/Chip ID register is used to determine whether the user is adding a COMET or COMETQUAD device. The device data block stores the device type (COMET or COMET-QUAD) in the cometqFlag field. Prototype Inputs sCMQ_HNDL cometqAdd(void *usrCtxt, UINT1 *baseAddr, INT4 **pperrDevice) usrCtxt baseAddr pperrDevice : user context for this device : base address of the device : (pointer to) an area of memory Outputs ERROR code written to the MDB on failure Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 73 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface pperrDevice : (pointer to) errDevice (inside the DDB) Returns Valid States Side Effects Device Handle (to be used as an argument to most of the COMET- QUAD APIs) or NULL (pointer) in case of an error CMQ_MOD_READY Changes the Device state to CMQ_PRESENT Deleting a Device: cometqDelete This function is used to remove the specified device from the list of devices being controlled by the COMET-QUAD driver. Deleting a device involves invalidating the DDB for that device and releasing its associated device handle. This API call is identical for both COMET and COMET-QUAD devices. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqDelete(sCMQ_HNDL deviceHandle) deviceHandle : device handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE None Initializing a Device: cometqInit Initializes the Device Data Block (DDB) associated with that device during cometqAdd, applies a soft reset to the device and configures it according to the DIV passed by the Application. If the DIV is passed as a NULL, the profile number is used. A profile number of zero indicates that all the register bits are to be left in their default state (after a soft reset). Note that the profile number is ignored UNLESS the passed DIV is NULL. To set the callbacks on a device while retaining the device in its reset state, the initDevice member of the DIV should be set to 0. The analogInit, backplaneInit, and framerInit members are then not applied to the hardware and are not validated before application of the DIV. This function is supported by both COMET and COMET-QUAD devices. For COMET devices, the backplane configuration modes in the DIV should not be H-MVIP or H-MVIP CCS. Prototype INT4 cometqInit(sCMQ_HNDL deviceHandle, sCMQ_DIV *pdiv, UINT2 profileNum) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 74 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Inputs deviceHandle pdiv profileNum : device Handle (from cometqAdd) : (pointer to) Device Initialization Vector : profile number (ignored if pdiv is NULL) Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_PRESENT Changes the DEVICE state to CMQ_INACTIVE Resetting a Device: cometqReset Applies a software reset to the COMET or COMET-QUAD device. Also resets all the DDB contents (except for the user context). This function is typically called before re-initializing the device (via cometqInit). This function is supported by both COMET and COMET-QUAD devices. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqReset(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE Changes the DEVICE state to CMQ_PRESENT Updating the Configuration of a Device: cometqUpdate Updates the configuration of the device as well as the Device Data Block (DDB) associated with that device according to the DIV passed by the Application. The only difference between cometqUpdate and cometqInit is that a soft reset is not applied to the device. In addition, a profile number of zero is not allowed if a DIV is not passed to the function. Prototype Inputs INT4 cometqUpdate(sCMQ_HNDL deviceHandle, sCMQ_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum : device handle (from cometqAdd) : (pointer to) Device Initialization Vector : profile number (only used if pdiv is NULL) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 75 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Activating a Device: cometqActivate This function activates a device by enabling interrupts. If the device was deactivated, the interrupt mask remains as it was prior to deactivation. Interrupts will be re-enabled if the device was in ISR mode. This function is supported by both COMET and COMET-QUAD. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqActivate(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_INACTIVE Changes the DEVICE state to CMQ_ACTIVE Deactivating a Device: cometqDeActivate Deactivates a device by disabling interrupts. The interrupt mask is retained within the DDB and is restored upon device activation. This function is supported by both COMET and COMET-QUAD devices. Prototype Inputs Outputs Returns Valid States INT4 cometqDeActivate(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 76 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Side Effects Changes the DEVICE state to CMQ_INACTIVE 4.4 Device Read and Write Reading from Device Registers: cometqRead This function can be used to read any one of the registers on a specific COMET or COMETQUAD device by providing the register number. This function derives the actual address location based on the device handle and register number inputs. It then reads the contents of this address location using the system specific macro, sysCometqRead. Note that a failure to read returns a zero and any error indication is written to the associated DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. This function is supported by both COMET and COMET-QUAD devices and behaves identically for both devices. Register address bounds checking is performed as is appropriate for the specific device. Prototype Inputs Outputs Returns Valid States Side Effects UINT1 cometqRead(sCMQ_HNDL deviceHandle, UINT2 regNum) deviceHandle regNum : device Handle (from cometqAdd) : register number ERROR code written to the DDB. If DDB is invalid, the error code is written to the MDB. Success = value read Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May affect registers that change after a read operation Writing to Device Registers: cometqWrite This function can be used to write any one of the registers on a specific COMET or COMETQUAD device by providing the register number. The function derives the actual address location based on the device handle and register number inputs. It then writes the contents of this address location using the system specific macro, sysCometqWrite. Note that a failure to write returns a zero and any error indication is written to the DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. This function is supported by both COMET and COMET-QUAD devices and behaves identically for both devices. Register address bounds checking is performed as is appropriate for the specific device. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 77 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype Inputs UINT1 cometqWrite(sCMQ_HNDL deviceHandle, UINT2 regNum, UINT1 value) deviceHandle regNum value : device Handle (from cometqAdd) : register number : value to be written Outputs Returns Valid States Side Effects ERROR code written to the DDB. If the DDB is invalid, the error code is written to the MDB. Success = value written Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May change the configuration of the Device Reading from a block of Device Registers: cometqReadBlock This function can be used to read a block of registers on a COMET or COMET-QUAD device by providing the starting register number and the size to read. This function derives the actual start address location based on the device handle and starting register number inputs. It then reads the contents of this data block using multiple calls to the system specific macro, sysCometqRead. Note that a failure to read returns a zero and any error indication is written to the DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. It is the USER's responsibility to allocate enough memory for the block read. This function is supported by both COMET and COMET-QUAD devices and behaves identically for both devices. Register address bounds checking is performed as is appropriate for the specific device. Prototype Inputs UINT1 cometqReadBlock(sCMQ_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT1 *pblock) deviceHandle startRegNum size : device Handle (from cometqAdd) : starting register number : size of the block to read Outputs ERROR code written to the DDB. If the DDB is invalid, the error code is written to the MDB. pblock : (pointer to) block read memory Returns Valid States Side Effects Last register value read CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May affect registers that change after a read operation Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 78 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Writing to a Block of Device Registers: cometqWriteBlock This function can be used to write to a block of registers on a COMET or COMET-QUAD device by providing the starting register number, the block size, and the data. This function derives the actual starting address location based on the device handle and starting register number inputs. It then writes the contents of this data block using multiple calls to the system specific macro, sysCometqWrite. A bit from the passed block is only modified in the device's registers if the corresponding bit is set in the passed mask. Note that any error indication is written to the DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. This function is supported by both COMET and COMET-QUAD devices and behaves identically for both devices. Register address bounds checking is performed as is appropriate for the specific device. Prototype Inputs UINT1 cometqWriteBlock(sCMQ_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT1 *pblock, UINT1 *pmask) deviceHandle startRegNum size pblock pmask : device Handle (from cometqAdd) : starting register number : size of block to read : (pointer to) block to write : (pointer to) mask Outputs Returns Valid States Side Effects ERROR code written to the DDB. If the DDB is invalid, the error code is written to the MDB. Last register value written CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May change the configuration of the Device Reading from Framer Device Registers: cometqReadFr This function can be used to read any one of the indirect registers on a specific COMET-QUAD device by providing the register number. This function derives the actual address location based on the device handle and register number inputs. It then reads the contents of this address location using the system specific macro, sysCometqRead. Note that a failure to read returns a zero and any error indication is written to the associated DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. This function is not supported by COMET devices as it contains only a single framer. Invocations of this API for a COMET device will fail with error code CMQ_ERR_INVALID_DEV. Prototype Inputs UINT1 cometqReadFr(sCMQ_HNDL deviceHandle, UINT1 frmNum, UINT2 regNum) deviceHandle : device Handle (from cometqAdd) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 79 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface frmNum regNum : framer number: 0, 1, 2, or 3 : register number Outputs Returns Valid States Side Effects ERROR code written to the DDB Success = value read Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May affect registers that change after a read operation Writing to Framer Device Registers: cometqWriteFr This function can be used to write to any one of the indirect registers on a specific COMETQUAD device by providing the register number. This function derives the actual address location based on the device handle and register number inputs. It then writes the contents of this address location using the system specific macro, sysCometqWrite. Note that a failure to write returns a zero and any error indication is written to the DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. This function is not supported by COMET devices as it provides only a single framer. Invocations of this API for a COMET device will fail with error code CMQ_ERR_INVALID_DEV. Prototype Inputs UINT1 cometqWriteFr(sCMQ_HNDL deviceHandle, UINT1 frmNum, UINT2 regNum, UINT1 value) deviceHandle frmNum regNum value : device Handle (from cometqAdd) : framer number: 0, 1, 2, or 3 : register number : value to be written Outputs Returns Valid States Side Effects ERROR code written to the DDB Success = value written Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May change the configuration of the Device Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 80 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Reading from Device Indirect Registers: cometqReadFrInd This function can be used to read any one of the indirect registers on a specific COMET or COMET-QUAD device by providing the indirect address and the indirect memory section. This function derives the actual address location based on the device handle and indirect address inputs. It then reads the contents of this address location using the system specific macro, sysCometqRead. Note that a failure to read returns a zero and any error indication is written to the associated DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. Note that the RLPS Equalizer RAM indirect registers are accessed through cometqReadRLPS and cometqWriteRLPS. Prototype Inputs UINT1 cometqReadFrInd(sCMQ_HNDL deviceHandle, UINT1 frmNum, eCMQ_SECTION section, UINT2 regNum) deviceHandle frmNum section : device Handle (from cometqAdd) : framer number: COMET-QUAD: 0, 1, 2, or 3 COMET: not used : section number: CMQ_SIGX_SECT, CMQ_TPSC_SECT, CMQ_RPSC_SECT, CMQ_XLPG_SECT regNum : indirect address Outputs Returns Valid States Side Effects ERROR code written to the DDB Success = value read Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May affect registers that change after a read operation Writing to Device Indirect Registers: cometqWriteFrInd This function can be used to write to any one of the indirect registers on a specific COMET or COMET-QUAD device by providing the indirect address and indirect memory section. This function derives the actual address location based on the device handle and indirect address inputs. It then writes the contents of this address location using the system specific macro, sysCometqWrite. Note that a failure to write returns a zero and any error indication is written to the DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. Note that the RLPS Equalizer RAM indirect registers are accessed through cometqReadRLPS and cometqWriteRLPS. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 81 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype UINT1 cometqWriteFrInd(sCMQ_HNDL deviceHandle, UINT1 frmNum, eCMQ_SECTION section, UINT2 regNum, UINT1 value) deviceHandle frmNum section Inputs : device Handle (from cometqAdd) : framer number: COMET-QUAD: 0, 1, 2, or 3 COMET: not used : section number: CMQ_SIGX_SECT, CMQ_TPSC_SECT, CMQ_RPSC_SECT, CMQ_XLPG_SECT regNum value : indirect address : value to be written Outputs Returns Valid States Side Effects ERROR code written to the DDB Success = value written Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May change the configuration of the Device Reading from Device RLPS Indirect Registers: cometqReadRLPS This function can be used to read any one of the RLPS indirect registers on a specific COMET or COMET-QUAD device. This function derives the actual address location based on the device handle and indirect address inputs. It then reads the contents of this address location using the system specific macro, sysCometqRead. Note that a failure to read returns a zero and any error indication is written to the associated DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. Prototype Inputs UINT4 cometqReadRLPS(sCMQ_HNDL deviceHandle, UINT1 frmNum, UINT1 regNum) deviceHandle frmNum regNum : device Handle (from cometqAdd) : framer number: COMET-QUAD: 0, 1, 2, or 3 COMET: not used : indirect address Outputs Returns Valid States Side Effects ERROR code written to the DDB Success = value read Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May affect registers that change after a read operation Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 82 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Writing to Device RLPS Indirect Registers: cometqWriteRLPS This function can be used to write to any one of the RLPS indirect registers on a specific COMET or COMET-QUAD device. This function derives the actual address location based on the device handle and indirect address inputs. It then writes the contents of this address location using the system specific macro, sysCometqWrite. Note that a failure to write returns a zero and any error indication is written to the DDB. In the event that the device handle passed to the function is invalid, the corresponding error code is written to the MDB. Prototype Inputs UINT4 cometqWriteRLPS(sCMQ_HNDL deviceHandle, UINT1 frmNum, UINT1 regNum, UINT4 value) deviceHandle frmNum regNum value : device Handle (from cometqAdd) : framer number: COMET-QUAD: 0, 1, 2, or 3 COMET: not used : indirect address : value to be written Outputs Returns Valid States Side Effects ERROR code written to the DDB Success = value written Failure = 0 CMQ_PRESENT, CMQ_ACTIVE, CMQ_INACTIVE May change the configuration of the Device 4.5 Interface Configuration The Interface Configuration section of the driver is used for configuring the COMET and COMET-QUAD T1/E1 line interfaces and the receive and transmit backplane interfaces, including the transmit and receive H-MVIP interfaces on the COMET-QUAD. These APIs allow the user to configure the receive and transmit line coding scheme to B8ZS, HDB3, or AMI, the receive and transmit analog characteristics, jitter attenuators and their associated timing options, and digital and analog loss of signal definitions. For both COMET and COMET-QUAD, the receive and transmit elastic stores can be configured through this interface in addition to backplane interface configuration. The Interface Configuration API does not provide a backplane profile mechanism. In order to configure the backplane based upon any of the standard configurations given in the device data sheets, the profile initialization API or a device initialization vector (DIV) must be used. Transmit line coding configuration: cometqLineTxEncodeCfg Allows configuration of the transmit line coding scheme. In T1 operational mode, selection between alternate mark inversion (AMI) and bipolar with eight zero substitution (B8ZS) is allowed. In E1 mode, the user can select either AMI or high density bipolar (HDB3) schemes. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 83 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype Inputs INT4 cometqLineTxEncodeCfg(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_LINE_CODE encScheme) deviceHandle chan encScheme : device Handle (from cometqAdd) : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used : transmit encoding scheme for E1/T1. One of: CMQ_LINE_CODE_AMI, CMQ_LINE_CODE_HDB3_E1, or CMQ_LINE_CODE_B8ZS_T1 Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Receive line coding configuration: cometqLineRxEncodeCfg Allows configuration of the receive line coding scheme. In T1 operational mode, selection between alternate mark inversion (AMI) and bipolar with eight zero substitution (B8ZS) is allowed. In E1 mode, the user can select either AMI or high density bipolar (HDB3) schemes. This function also allows the user to configure the bipolar violation definition. Prototype INT4 cometqLineRxEncodeCfg(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_LINE_CODE encScheme, UINT1 incXSZeros, UINT1 E1_O162En) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 encScheme Inputs COMET: not used : transmit encoding scheme for E1/T1. One of: CMQ_LINE_CODE_AMI, CMQ_LINE_CODE_HDB3_E1, or CMQ_LINE_CODE_B8ZS_T1 incXSZeros : indication to include excess zero violations as bipolar violations. Excess zero run lengths are 5 bits for T1 AMI, 8 bits in T1 B8ZS, and 4 bits for both E1 schemes : enable the O.162 bipolar violation definition (E1 only) E1_O162En Outputs None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 84 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Returns Success = CMQ_SUCCESS Failure = Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Analog transmitter configuration: cometqLineTxAnalogCfg Allows configuration of the transmit analog interface including the waveform scale factor, the waveform pulse shape, transmit tri-state, and fuse programming. Prototype Inputs INT4 cometqLineTxAnalogCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_TX_ANALOG* ptxAnalogCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used ptxAnalogCfg : transmit analog configuration structure Outputs Returns None Success = CMQ_SUCCESS Failure = Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Analog receiver configuration: cometqLineRxAnalogCfg Configures the analog line receive interface including analog loss of signal thresholds and periods and equalizer feedback frequency and stabilization period. Also, the equalizer RAM can be configured through this function. Prototype Inputs INT4 cometqLineRxAnalogCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_RX_ANALOG* prxAnalogCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used prxAnalogCfg : receive analog configuration structure Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 85 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Transmit jitter attenuator configuration: cometqLineTxJatCfg Configures the line transmit interface jitter attenuator by allowing the user to select bypass, clock divisors, and reference clocks. Prototype Inputs INT4 cometqLineTxJatCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_TX_JAT *ptxJatCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 ptxJatCfg COMET: not used : transmit jitter configuration data Outputs Returns None Success = CMQ_SUCCESS Failure = Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects Implicitly sets voltage reference of the analog receiver's equalizer based on the operational mode. Receive jitter attenuator configuration: cometqLineRxJatCfg Configures the line receive interface jitter attenuator by allowing the user to select jitter attenuator bypass and clock divisors. Prototype Inputs INT4 cometqLineRxJatCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_RX_JAT *prxJatCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 prxJatCfg COMET: not used : receive jitter configuration data Outputs Returns None Success = CMQ_SUCCESS Failure = Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 86 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Clock service unit configuration: cometqLineClkSvcCfg This API function allows the user to configure the clock service unit operating mode. The user can select between a straight mapping of 2.048 MHz onto 2.048 MHz or 1.544 MHz onto 1.544 MHz as well as the option of transmitting at a 1.544 MHz line rate when the XCLK input is 2.048 MHz. This function is supported by both COMET and COMET-QUAD devices. Prototype Inputs INT4 cometqLineClkSvcCfg(sCMQ_HNDL deviceHandle, eCMQ_CSU_SVC_CLK synthTxFreq) deviceHandle synthTxFreq : device Handle (from cometqAdd) : synthesis clock frequency and transmit clock clock frequency. Select one of: CMQ_XCLK_2048_TXCLK_2048, CMQ_XCLK_1544_TXCLK_1544, or CMQ_XCLK_2048_TXCLK_1544 Outputs Returns None Success = CMQ_SUCCESS Failure = Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Receive clock and data recovery options: cometqLineRxClkCfg Configures the line receive interface clock and data recovery characteristics including the clock and data recovery algorithm and the digital loss of signal threshold. Note that selection of either CMQ_LOS_THRESH_PCM_10_HDB3 (E1 only), CMQ_LOS_THRESH_PCM_15_B8ZS (T1 only), or CMQ_LOS_THRESH_PCM_15_AMI as the loss of signal threshold will set the receive line coding scheme to the specified value, overriding the current setting. Prototype Inputs INT4 cometqLineRxClkCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_RX_CLK *prxClkCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 prxClkCfg COMET: not used : receive clock and data recovery structure Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 87 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects The line coding scheme will change if one of CMQ_LOS_THRESH_PCM_10_HDB3, CMQ_LOS_THRESH_PCM_15_B8ZS, or CMQ_LOS_THRESH_PCM_15_AMI was selected as the loss of signal threshold Backplane transmit interface configuration: cometqBTIFAccessCfg This function allows selection between transmit backplane master/slave modes as well as basic backplane data mode configuration. Prototype Inputs INT4 cometqBTIFAccessCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_BACKPLANE_ACCESS_CFG *pBTIFCfgData) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used pBTIFCfgData : backplane transmit interface configuration structure Outputs Returns None Success = CMQ_SUCCESS Failure = Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Backplane transmit interface configuration: cometqBTIFFrmCfg This function allows configuration of the transmit backplane interface frame pulse, parity odd/even selection and inversion, as well as frame pulse bit offset and T1 ESF alignment. Prototype Inputs INT4 cometqBTIFFrmCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_BTIF_FRM* pfrmCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 pfrmCfg COMET: not used : backplane transmit interface framing structure Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 88 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States CMQ_ACTIVE, CMQ_INACTIVE Side Effects None Backplane receive interface configuration: cometqBRIFAccessCfg This function allows selection between receive backplane master/slave modes as well as basic backplane data mode configuration. Prototype Inputs INT4 cometqBRIFAccessCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_BACKPLANE_ACCESS_CFG* pBRIFCfgData) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used pBRIFCfgData : backplane receive interface configuration structure Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Backplane receive interface configuration: cometqBRIFFrmCfg The user is able to configure the backplane receive interface frame pulse mode, parity configuration, frame pulse bit offset, bit fixing, T1 ESF insertion, and timeslot mapping through the use of this function. Prototype Inputs INT4 cometqBRIFFrmCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_BRIF_FRM *pfrmCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 pfrmCfg COMET: not used : backplane receive interface framing structure Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 89 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Receive and transmit HMVIP interfaces configuration: cometqHMVIPCfg This function provides configuration of the H-MVIP receive and transmit interfaces for COMETQUAD devices. This function is not supported by COMET devices. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqHMVIPCfg(sCMQ_HNDL deviceHandle, sCMQ_CFG_HMVIP *pHMVIPCfg) deviceHandle : device Handle (from cometqAdd) pHMVIPCfg : H-MVIP interface configuration structure None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Receive elastic store configuration: cometqRxElstStCfg This function provides configuration of the elastic store in the receive data path. The user can select whether or not to bypass the receive elastic store and configure the idle codes for both the PCM data stream (COMET and COMET-QUAD) and the CCS stream (COMET-QUAD only). Prototype Inputs INT4 cometqRxElstStCfg(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_RX_ELST* pElstCfg) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 pElstCfg COMET: not used : elastic store configuration data Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Transmit elastic store configuration: cometqTxElstStCfg This function configures the elastic store in the transmit data path. The user can select whether or not to bypass the transmit elastic store. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 90 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype Inputs INT4 cometqTxElstStCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 elstEnable) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 elstEnable COMET: not used : enable the elastic store or force bypass Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None 4.6 T1 /E1 Framers This section of the driver configures and monitors the T1/E1 Framers. The T1 framers can be configured to detect and transmit ESF, SF, J1 and the other T1 variants supported by the COMET and COMET-QUAD. The E1 framer can be configured to detect and transmit basic frame alignment or CRC-4multiframe with additional criteria to generate/detect channel associative signaling. Set Device Operational Mode: cometqSetOperatingMode This function specifies whether the device will operate in T1 or E1 mode. If cometqInit was called and hardware initialization was not specified, this function must be called immediately after device initialization. The behavior of subsequent calls to the configuration APIs throughout the driver assumes correct operating mode configuration. Configuration via any of the APIs throughout the driver may not be correct if cometqSetOperatingMode is not executed first. The following device configuration is performed based on the operating mode: * The RLPS voltage reference is configured as specified on the data sheet for the current device operation mode. Note that these values differ for the COMET and COMET-QUAD and are programmed accordingly RX-ELST Configuration register is configured to reflect the operating mode on both COMET and COMET-QUAD devices RX-ELST CCS Configuration register is configured to the reflect operating mode on the COMET-QUAD only TX-ELST Configuration register is configured to reflect the operating mode on both COMET and COMET-QUAD devices * * * Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 91 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface * TX-ELST CCS Configuration register is configured to the reflect operating mode on the COMET-QUAD only For COMET-QUAD devices, all four framers operate in the same operational mode as it is a global device value. Prototype Inputs INT4 cometqSetOperatingMode(sCMQ_HNDL deviceHandle, eCMQ_OPER_MODE operMode) deviceHandle : device Handle (from cometqAdd) operMode : Selects either T1 or E1 mode: CMQ_MODE_E1, CMQ_MODE_T1 Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_INACTIVE RLPS Equalizer Loop Voltage Reference, RX-ELST Configuration, TXELST Configuration, RX-ELST CCS Configuration (COMET-QUAD), and TX-ELST CCS Configuration (COMET-QUAD) registers configured to reflect operating mode T1 transmit framer configuration: cometqT1TxFramerCfg This function configures the transmit framing format and the zero code suppression format. Also, the user can enable the signal aligner block (SIGA) between the backplane and the transmit framer. Prototype Inputs INT4 cometqT1TxFramerCfg (sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_T1TX_FRM *pfrmCfg) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 pfrmCfg COMET: not used : T1 transmit framer configuration structure Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 92 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface T1 receive framer configuration: cometqT1RxFramerCfg This function provides the interface to configure the receive framing format and out of frame criteria. Also, if the frame format is ESF, the user can select the framing algorithm. Selection between use of frame alignment (COFA) event counts or out of frame alignment (OOFA) event counts in the PMON block can be configured here as well. Based on the framing format specified in pfrmCfg, the alarm integrator (ALMI) is configured for the T1 framing format and the signaling extractor (SIGX) block is configured for ESF if ESF is the selected framing format. Prototype Inputs INT4 cometqT1RxFramerCfg (sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_T1RX_FRM *pfrmCfg) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 pfrmCfg COMET: param not used : T1 receive framer configuration Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE Framing format is configured in SIGX and ALMI device blocks E1 transmit framer configuration: cometqE1TxFramerCfg This function provides an interface to configure the E1 transmit framing characteristics. The user is able to specify whether or not to generate CRC-4 multiframes and the type of signaling, if any, to insert into timeslot 16. Also, the user can enable or disable the insertion of national bits, international bits, extra bits, and the FEBE indicator bits through this API. Prototype Inputs INT4 cometqE1TxFramerCfg (sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_E1TX_FRM *pfrmCfg) deviceHandle : device Handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 pfrmCfg COMET: not used : E1 transmit framer configuration structure Outputs Returns Valid States None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 93 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Side Effects None E1 receive framer configuration: cometqE1RxFramerCfg This API allows the user to configure the receive framing format and specify whether or not to align to signaling multiframes. In addition to basic framing and signaling configuration, the user can specify the criteria for AIS, RAI, framing errors, and loss of frame detection. Prototype Inputs INT4 cometqE1RxFramerCfg (sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CFG_E1RX_FRM *pfrmCfg) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 pfrmCfg COMET: not used : E1 receive framer configuration Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None E1 transmit framer extra bits insertion: cometqE1TxSetExtraBits This API allows the user to set the extra bit values that will be inserted into bits 5, 7, and 8 of timeslot 16 in the first frame of every signaling multiframe. Note that these bits will only be inserted if the user has enabled extra bit insertion in the E1 transmit framer configuration. Prototype Inputs INT4 cometqE1TxSetExtraBits(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 extraBits) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 extraBits COMET: not used : bitmap containing extra bits information bit 0: X1 (timeslot 16, bit 5) bit 1: X3 (timeslot 16, bit 7) bit 2: X4 (timeslot 16, bit 8) bits 3-7: unused Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 94 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States Side Effects CMQ_ACTIVE, CMQ_INACTIVE None E1 transmit framer international bits configuration: cometqE1TxSetIntBits This API provides the user with an interface to set the value of the international bits to insert into the E1 stream. The user can specify two bits, one for FAS frames and the other for NFAS frames. Note that insertion of the international bits must already be enabled in the transmit framer. Prototype Inputs INT4 cometqE1TxSetIntBits(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 intBits) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 intBits COMET: not used : bitmap containing international bits bit 0 : Si[0]: inserted into NFAS frames bit 1: Si[1]: inserted into FAS frames bit 2-7 : unused Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None E1 transmit framer national bits configuration: cometqE1TxSetNatBits This function allows the user to set the national bit codeword for each of the five national bits in timeslot 0 of an NFAS frame. The codeword consists of four bits, one for each NFAS frame in a submultiframe. The user can enable or disable insertion of each of the four bits within the codeword. National bit insertion must be enabled in the E1 transmit framer for transmission of the national bits. Prototype INT4 cometqE1TxSetNatBits(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_E1_NAT_BIT codeSelect, UINT1 natBits, UINT1 natBitsEn) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 codeSelect Inputs COMET: not used : selects the national bit codeword to set: CMQ_E1_NAT_BIT_SA4, CMQ_E1_NAT_BIT_SA5, Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 95 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface CMQ_E1_NAT_BIT_SA6, CMQ_E1_NAT_BIT_SA7, CMQ_E1_NAT_BIT_SA8 natBits : bitmap containing national bit values (over one submultiframe) bit 0 : first Sai position in SMF bit 1 : second Sai position in SMF bit 2 : third Sai position in SMF bit 3 : fourth Sai position in SMF bits 4-7 : unused : enables/disables each bit position in natBits: bit 0 : enable first Sai bit bit 1 : enable second Sai bit bit 2 : enable third Sai bit bit 3 : enable fourth Sai bit bits 4-7 : unused natBitsEn Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None E1 receive framer extra bit extraction: cometqE1RxGetExtraBits This API provides the value of the extra bits and the y bit from timeslot 16, frame 0 of the last received signaling multiframe. Prototype Inputs INT4 cometqE1RxGetExtraBits(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1* pExtraBits) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs pExtraBits : bitmap containing extra bits & y bit bit 0 : X1 (from timeslot 16, bit 5) bit 1 : Y bit (from timeslot 16, bit 6) bit 2 : X3 (from timeslot 16, bit 7) bit 3 : X4 (from timeslot 16, bit 8) bits 4-7 : unused Returns Success = CMQ_SUCCESS Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 96 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Failure = CMQ_ACTIVE, CMQ_INACTIVE None E1 receive framer international bit extraction: cometqE1RxGetIntBits This function returns the international bits from the incoming E1 stream for the last frame. Si[0] is updated every NFAS frame while Si[1] is updated every FAS frame. Prototype Inputs INT4 cometqE1RxGetIntBits(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1* pIntBits) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs pIntBits : bitmap containing international bits bit 0 : Si[0]: inserted into NFAS frames bit 1 : Si[1]: inserted into FAS frames bit 2-7: unused Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None E1 receive framer national bit extraction: cometqE1RxGetNatBitsNFAS This function returns the value of the national bits from the incoming E1 stream from the last NFAS frame. This API allows the user to process the national bits on a frame by frame basis, without waiting for the complete submultiframe. Prototype Inputs INT4 cometqE1RxGetNatBitsNFAS(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1* pNatBits) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs pNatBits : bitmap containing national bit values bit 0 : Sa 4 bit 1 : Sa 5 bit 2 : Sa 6 bit 3 : Sa 7 bit 4 : Sa 8 97 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface bits 5-7 : unused Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None E1 receive framer national bit extraction: cometqE1RxGetNatBitsSMFRM This function returns a complete national bit codeword for a specified national bit in the incoming E1 stream for the last submultiframe. Prototype INT4 cometqE1RxGetNatBitsSMFRM(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_E1_NAT_BIT codeSelect, UINT1* pNatBits) deviceHandle : device handle (from cometqAdd) chan : E1 channel: COMET-QUAD: 0, 1, 2, or 3 Inputs COMET: not used codeSelect : selects the national bit codeword to extract: CMQ_E1_NAT_BIT_SA4, CMQ_E1_NAT_BIT_SA5, CMQ_E1_NAT_BIT_SA6, CMQ_E1_NAT_BIT_SA7, CMQ_E1_NAT_BIT_SA8 Outputs pNatBits : bitmap containing national bit values (over one submultiframe) bit 0 : first Sai position in SMF bit 1 : second Sai position in SMF bit 2 : third Sai position in SMF bit 3 : fourth Sai position in SMF bits 4-7 : unused Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 98 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface 4.7 Signal Insertion/Extraction This section of the driver provides the framework to examine channel associative signaling in the receive T1 or E1 stream and to detect a change of signaling state event. Also an interface to manipulate the data stream on a DS0 basis through the SIGX block on the device is provided. Change of signaling state detection: cometqExtractCOSS This function provides a bitmap corresponding to change of signaling state (COSS) information for a T1 or E1 stream. After determining on which E1 timeslot or T1 channel the signaling state has changed through the use of this function, the user should call cometqSigExtract for the new signaling state. Prototype Inputs INT4 cometqExtractCOSS(sCMQ_HNDL deviceHandle, UINT2 chan, UINT4 *psigState) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs : Signal state bit map. E1: Bit 0 corresponds to timeslot 1 and bit 30 corresponds to timeslot 31. Timeslot 0 and 16 do not have COSS info. Bit 15 (timeslot 16) is always set to 0. Bit 31 is unused and set to zero. Bits 0 to 23 correspond to timeslots 1 to 24 respectively. Bits 24 to 31 are not used and set to 0. pSigState T1: Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Signaling state extraction: cometqSigExtract This API extracts signaling bits for a single E1 timeslot or T1 channel from the receive stream. Note that upon a COSS event, these values are not updated until the next signaling multiframe. Prototype INT4 cometqSigExtract(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 timeslot, UINT1* pSigState) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 99 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Inputs deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used timeslot : timeslot for which to retrieve signaling. For T1, this value should be from 1-24. When in E1 mode, this value should range from 1-31 as there is no signaling info for timeslot 0. : contains the signaling state information for the timeslot. bit 0: D bit bit 1: C bit bit 2: B bit bit 3: A bit bits 4-7: unused Outputs pSigState Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Signal trunken: cometqSigTslotTrnkDataCfg This API allows the user to enable change of signal state debouncing by only allowing a COSS event to be generated when the new signaling data is received twice consecutively. Also, DS0 manipulation of the PCM data stream can be performed here. DS0 PCM data manipulation performed by the signal extraction block occurs before PCM data manipulation performed by the RPSC block (via cometqRPSCPCMCtrl). Prototype INT4 cometqSigTslotTrnkDataCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT2 readWrite, UINT1 timeslot, UINT1* pSigConfig) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 readWrite timeslot Inputs COMET: not used : Read data = 0 : Write data = 1 : timeslot to operate on. For T1, this value should be from 1-24. When in E1 mode, this value should range from 0-31. : pointer to config data when writing pSigConfig Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 100 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Outputs pSigConfig : pointer to config data bit map for T1 mode: bit 0: enable COSS debouncing bit 1: logic level when bit fixing enabled bit 2: enable bit fixing bit 3: invert all PCM data bits bit 4-7: unused bit map for E1 mode: bit 0: enable COSS debouncing bit 1: unused bit 2,3: 0,0 - no inversion 0,1 - invert odd PCM bits 1,0 - invert even PCM bits 1,1 - invert all bits bit 4-7: unused Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None 4.8 Alarm and Inband Communications This section of the driver provides an interface to configure alarms, configure and use the HDLC transmitter and receiver, and transmit and receive bit oriented codes (BOCs). Alarms configuration includes forced insertion of alarms such as AIS and yellow alarms into the transmit stream as well as automatic handling of alarm conditions on the receive line. Automatic alarm response configuration: cometqAutoAlarmCfg This function allows the user to enable or disable the possible automatic alarm response on detection of AIS, yellow alarms, red alarms, and out of frame. For an out of frame event, data conditioning can be enabled from the receive elastic stores or the RPSC idle code registers. Prototype INT4 cometqAutoAlarmCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 autoYellowEn, UINT1 autoRedEn, UINT1 OOF_RPSCEn, UINT1 OOF_RxELSTEn, UINT1 autoAISEn) deviceHandle : device Handle (from cometqAdd) Inputs Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 101 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface COMET-QUAD: 0, 1, 2, or 3 COMET: not used autoYellowEn : enables automatic generation of yellow (E1 RAI) alarms in the receive direction upon a red alarm autoRedEn : enables automatic trunk conditioning onto the backplane data and signaling streams from the RPSC upon a red carrier fail alarm condition OOF_RPSCEn : enables automatic trunk conditioning onto the backplane data stream for the duration of out of frame. The conditioning data is inserted from the RPSC registers OOF_RxELSTEn : enables automatic trunk conditioning onto the backplane data stream for the duration of out of frame. The conditioning data is inserted from the Rx Elastic store idle code registers autoAISEn : enables automatic insertion of AIS into the receive path upon loss of signal chan : E1/T1 channel: Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Alarm insertion: cometqInsertAlarm This function allows the user to insert or to disable insertion of alarms into the data stream. The user can insert AIS into the receive stream (onto the backplane) or transmit yellow and AIS alarms for both T1 and E1. In addition, for E1 data, timeslot 16 y bit alarms and timeslot 16 AIS can also be inserted or disabled. Prototype Inputs INT4 cometqInsertAlarm(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_ALARM_INS alarmType, UINT1 enable) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 alarmType COMET: not used : type of alarm to activate/deactivate: CMQ_ALARM_INS_RX_AIS - force AIS into receive backplane interface CMQ_ALARM_INS_TX_YELLOW - transmit yellow alarm (RAI for E1) CMQ_ALARM_INS_TX_AIS - force AIS into transmit stream CMQ_ALARM_INS_TX_E1_Y_BIT - E1 only. Sends the timeslot 16 Y-bit alarm Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 102 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface CMQ_ALARM_INS_TX_E1_TS16_AIS - E1 only. Transmits AIS in timeslot 16 enable : selects activation or deactivation of the specified alarm Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC configuration: cometqHDLCEnable Enables or disables an HDLC link by enabling its respective input clocks and the associated TDPR and RDLC blocks. Prototype Inputs INT4 cometqHDLCEnable(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT2 enable) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or 2 enable : enable HDLC controller if set Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC configuration: cometqHDLCRxCfg Configures the receive HDLC controller for a data link on a COMET or COMET-QUAD device. This function allows you to configure where the receive data link is extracted from. It also enables address matching and masking. Prototype Inputs INT4 cometqHDLCRxCfg(sCMQ_HNDL deviceHandle, UINT2 idHDLC, sCMQ_CFG_HDLC_RX* pData) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 pData COMET: 0, 1, or 2 : HDLC receiver configuration data 103 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC configuration: cometqHDLCTxCfg Configures the HDLC transmitter for a data link on a COMET or COMET-QUAD device. This function allows configuration of where the data link is inserted as well as options such as flag sharing, CRC frame check sequences, and performance report insertion. Prototype Inputs INT4 cometqHDLCTxCfg(sCMQ_HNDL deviceHandle, UINT2 idHDLC, sCMQ_CFG_HDLC_TX* pData) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 pData Outputs Returns Valid States Side Effects None COMET: 0, 1, or 2 : HDLC transmitter configuration data Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC transmitter: cometqTDPRData This function transmits a data byte on the specified HDLC link. Prototype Inputs INT4 cometqTDPRData(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT1 value) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 value COMET: 0, 1, or 2 : byte to transmit on data link Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 104 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States Side Effects CMQ_ACTIVE, CMQ_INACTIVE None HDLC transmitter: cometqTDPRCtl With this function the user can transmit a control byte on an HDLC link or force a FIFO clear. Prototype Inputs INT4 cometqTDPRCtl(sCMQ_HNDL deviceHandle, UINT2 idHDLC, eCMQ_TDPR_ACTION hdlcAction) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or 2 hdlcAction : CMQ_TDPR_ACTION_ABORT - insert HDLC abort code into data link CMQ_TDPR_ACTION_END_ABORT - end abort code insertion CMQ_TDPR_ACTION_EOM - send end of message indicator CMQ_TDPR_ACTION_FIFOCLR - clear transmit fifo Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC transmitter: cometqTDPRFIFOThreshCfg Configures the upper and lower limits of the HDLC transmitter FIFO for one of the transmit HDLC Controllers. Prototype Inputs INT4 cometqTDPRFIFOThreshCfg(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT1 upFifoThresh, UINT1 lowFifoThresh) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or upFifoThresh : upper FIFO threshold for auto transmit valid values are 0 thru 127 lowFifoThresh: lower FIFO threshold for LFILL interrupt valid values are 0 thru 127 Note that the lower threshold must be less than upper threshold unless both are set to 0. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 105 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC transmitter: cometqTDPRTx This function transmits an HDLC packet on the specified HDLC link. If this function returns CMQ_ERR_FIFO_UNDERRUN, a FIFO underrun has occurred and the packet should be retransmitted. Prototype Inputs INT4 cometqTDPRTx(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT1* pPacket, UINT2 packetLength) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or pPacket : Buffer containing packet to transmit packetLength : Number of bytes in packet to transmit. Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE None HDLC receiver: cometqRDLCTerm Forces the RDLC to immediately terminate the reception of the current data frame. This function causes the current data frame to terminate and the FIFO buffer to empty. The RDLC then begins searching for a frame delimiting flag. Prototype Inputs INT4 cometqRDLCTerm(sCMQ_HNDL deviceHandle, UINT2 idHDLC) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or 2 Outputs Returns None Success = CMQ_SUCCESS Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 106 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC receiver: cometqRDLCAddrMatch This function configures the primary and secondary addresses used with address matching on an HDLC receiver. When address masking is enabled, the lower two bits of each of the primary and secondary addresses are masked during comparison. Prototype Inputs INT4 cometqRDLCAddrMatch(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT1 addrPri, UINT1 addrSec) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or 2 addrPri addrSec : primary address : secondary address Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None HDLC receiver: cometqRDLCFIFOThreshCfg Configures the fill level threshold for an RDLC FIFO. The fill level threshold is the number of bytes that must be present in the FIFO before an interrupt is generated. Prototype Inputs INT4 cometqRDLCFIFOThreshCfg(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT1 fifoThresh) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or 2 fifoThresh : FIFO fill level threshold (7 bit value) Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 107 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States Side Effects CMQ_ACTIVE, CMQ_INACTIVE None HDLC receiver: cometqRDLCRx This function services an RDLC interrupt condition and should be called when an RDLC interrupt has occurred or periodically to poll the RDLC on a COMET or COMET-QUAD device to check for activity on the HDLC link. When this function is invoked, the return code indicates the status of RDLC data processing. cometqRDLCRx should be repeatedly called until CMQ_SUCCESS is returned. The return codes should be interpreted as follows: * CMQ_SUCCESS : The RDLC FIFO is empty and cometqRDLCRx need not be called again until the next RDLC interrupt event occurs. If pPacketStatus is set to CMQ_HDLC_PACKET_INCOMPLETE, an incomplete packet was written to pPacket. The number of bytes written to the buffer is given by pBytesWritten. The buffer pointer pPacket should be incremented by this number of bytes when the next RDLC interrupt occurs in order for cometqRDLCRx to continue writing the packet from its previous position. * CMQ_ERR_CHANGE_OF_LINK_STATE : A change of link state event has been detected. The new link state is returned in pLinkStateFlag. cometqRDLCRx should be called again after the change of link state has been processed. CMQ_ERR_PACKET_COMPLETE : Indicates that a packet was terminated in pPacket. pPacketStatus specifies whether a CRC error or non-integral byte count error occurred. cometqRDLCRx should be called again. CMQ_ERR_FIFO_OVERRUN : The HDLC receiver FIFO has overflowed. Any incomplete packets (status CMQ_HDLC_PACKET_INCOMPLETE) must be discarded and cometqRDLCRx should be called again. * * Prototype Inputs INT4 cometqRDLCRx(sCMQ_HNDL deviceHandle, UINT2 idHDLC, UINT2* pLinkStateFlag, UINT2* pBytesWritten, UINT1* pPacketStatus, UINT1* pPacket) deviceHandle : device Handle (from cometqAdd) idHDLC : HDLC controller: COMET-QUAD: 0, 1, 2, or 3 COMET: 0, 1, or pLinkStateFlag : pointer to link state flag Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 108 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface pBytesWritten pPacketStatus pPacket pLinkStateFlag : pointer to byte count : pointer to packet status : packet buffer : new link state on a change of link state event 0 => inactive, 1 => active : number of bytes written to pPacket : bitmap containing status of packet written to and without errors Outputs pBytesWritten pPacketStatus pPacket: CMQ_HDLC_PACKET_OKAY => the packet is complete CMQ_HDLC_PACKET_CRC_ERR => the packet is complete but contains a CRC error CMQ_HDLC_PACKET_NON_INTEGER_BYTES => the packet is complete but contained a non-itegral number of bytes and should be discarded CMQ_HDLC_PACKET_INCOMPLETE => the packet is not yet complete CMQ_HDLC_PACKET_NONE => no data was been written to the buffer pPacket : packet buffer Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE None Inband loopack code detection: cometqIBCDActLpBkCfg Configures the detection of inband activate loopback code length and pattern. This API is valid only in T1 mode. Prototype Inputs INT4 cometqIBCDActLpBkCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 patLen, UINT1 pat) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 patLen pat COMET: not used : pattern length (5-8) : activate loopback pattern Outputs None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 109 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Inband loopack code detection: cometqIBCDDeActLpBkCfg Configures the detection of inband deactivate loopback code length and pattern. This API is valid only in T1 mode. Prototype Inputs INT4 cometqIBCDDeActLpBkCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 patLen, UINT1 pat) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 patLen pat COMET: not used : pattern length (5-8) : deactivate loopback pattern Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Inband loopack code transmission: cometqIBCDTxCfg Enables/disables transmission of the inband transmit loopback code and allows configuration of the code length and pattern when activating. When disabling transmission of the loopback code, the parameters pat and patLen are not used. This API is valid only in T1 mode. Prototype Inputs INT4 cometqIBCDTxCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 patLen, UINT1 pat, UINT2 enable) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used patLen pat enable : pattern length (5-8). Only used when enabling. : loop code pattern. Only used when enabling. : enable/disable loopback code transmission Outputs None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 110 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Bit Oriented Code transmission: cometqBOCTxCfg Configures the bit oriented code for transmission,. On COMET-QUAD devices, the associated repeat count can also be configured. The value of parameter boc is transmitted with the least significant bit leading. To terminate BOC transmission, boc should be set to all 1's. Valid only in T1 mode. Prototype Inputs INT4 cometqBOCTxCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 boc, UINT1 repCount) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 boc repCount COMET: not used : 6 bit BOC code pattern. Setting this value to all 1's disables BOC transmission : number of consecutive BOC codes to transmit. Valid range is 0 thru 15. Supported by COMET-QUAD only. Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Bit Oriented Code detection: cometqBOCRxCfg Configures bit oriented code detection criteria by allowing the user to select the threshold that determines whether or not a valid BOC code has been detected. Valid BOC detection criteria are 8 out of 10 matching values (or alternately 4 out of 5 matching values). Valid only in T1 mode. Prototype Inputs INT4 cometqBOCRxCfg(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_RBOC_CRITERIA detectCriteria) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 detectCriteria COMET: not used : CMQ_RX_BOC_VALID_4OF5 - 4 out of 5 of the same BOC code Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 111 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface received CMQ_RX_BOC_VALID_8OF10 - 8 out of 10 of the same BOC code received Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Bit Oriented Code detection: cometqBOCRxGet This API retrieves the current bit oriented code from the holding registers. Valid only in T1 mode. Prototype Inputs INT4 cometqBOCRxGet(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 *prxBOC) deviceHandle : device Handle (from cometqAdd) chan : T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs Returns Valid States Side Effects : pointer to last BOC received (6 bit value) prxBoc Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None 4.9 Serial Control This section provides the user with an interface to manipulate the T1 or E1 stream on a DS0 basis; the user can force signal or trunk conditioning on any given timeslot or manipulate the PCM data. Also, this section provides access to the on-chip pseudo random generator/detector, allowing the user to configure the pattern and insert random data into the data stream. Transmit per-channel serial controller: cometqTPSCEnable This function enables or disables the Transmit Per-Channel Serial Controller (TPSC) to manipulate signaling and data for all 24 T1 channels or all 32 E1 timeslots. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 112 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype Inputs INT4 cometqTPSCEnable(sCMQ_HNDL deviceHandle, UINT2 chan, UINT2 enable) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 enable COMET: not used : enable/disable Transmit Serial Controller Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Transmit per-channel serial controller: cometqTPSCPCMCtl This function allows the user to invoke PCM data inversion, idle pattern insertion, DS0 loopback, and zero code suppression. The user can also force insertion of signaling bits by providing their own signaling data. Prototype INT4 cometqTPSCPCMCtl(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 tSlot, UINT2 rWFlag, UINT1 *pctlByte, UINT1 *ptrnkData, UINT1 *psigData) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 tSlot Inputs rWFlag pctlByte COMET: not used : timeslot E1: 0 thru 31 T1: 1 thru 24 : Read/Write select. Write = 1, Read = 0 : pcm data control byte bit 7,5: 0,0 - data unchanged 0,1 - only msb inverted 1,0 - inverted all bits 1,1 - invert all except msb bit 6: replace pcm data with trunk conditioning byte bit 4: (T1 only) replace pcm data with digital mW pattern bit 3: if receive pattern generation on, data routed to PRBS/PRGD checker otherwise overwritten with PRBS/PRGD test pattern bit 2: loopback DS0 bit 1,0: zero code suppression format 113 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface 0,0 - no zero suppression 0,1 - jammed bit 8 1,0 - GTE zero suppression 1,1 - Bell zero suppression ptrnkData psigData : trunk conditioning data byte : signaling data byte / E1 control byte bit map for E1 mode: bit 7,6,5: data manipulation 0,0,0 - data unchanged 0,0,1 - invert odd timeslot bits 0,1,0 - invert even timeslot bits 0,1,1 - invert all timeslot bits 1,0,0 - replace data with idle code 1,0,1 - replace data with idle code 1,1,0 - replace data with A-law pattern 1,1,1 - replace data with U-law pattern bit 4: when CAS enabled, signaling bits taken from A,B,C,D bits bit 3,2,1,0: A,B,C,D bits bit map for T1 mode: bit 7: forces signaling data from A,B,C,D bits bit 6: enables signal insertion from ABCD bits bit 5,4: unused bit 3,2,1,0: A,B,C,D bits Outputs pctlByte ptrnkData psigData : control byte : trunk conditioning data byte : signaling data byte Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Receive per-channel serial controller: cometqRPSCEnable This function enables or disables the Receive Per-Channel Serial Controller (RPSC) to manipulate signaling and data for all 24 T1 channels or all 32 E1 timeslots. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 114 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Prototype Inputs INT4 cometqRPSCEnable(sCMQ_HNDL deviceHandle, UINT2 chan, UINT2 enable) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 enable COMET: not used : enable/disable Receive Serial Controller Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Receive per-channel serial controller: cometqRPSCPCMCtl Through the use of this function, the user can force data trunk conditioning on any individual timeslot, force insertion of A-law or u-law patterns, or retrieve signaling information. Also, the user can force PCM data inversion, idle pattern insertion, DS0 loopback, and zero code suppression. The user can also force insertion of signaling bits by providing the signaling data to the signaling bits. DS0 PCM data manipulation performed by the RPSC occurs after PCM data manipulation performed in the SIGX block (cometqSigTslotTrnkDataCfg). Prototype INT4 cometqRPSCPCMCtl(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 tSlot, UINT2 rWFlag, UINT1 *pctlByte, UINT1 *ptrnkData, UINT1 *psigData) deviceHandle : device Handle (from cometqAdd) chan tSlot Inputs : E1/T1 channel: : timeslot E1: 0 thru 31 T1: 1 thru 24 COMET-QUAD: 0, 1, 2, or 3 COMET: not used rWFlag pctlByte : Read/Write select. Write = 1, Read = 0 : Control byte bit 7: if receive pattern generation off, data routed to PRBS/PRGD checker otherwise overwritten with PRBS/PRGD test pattern bit 6: overwrite data with data trunk conditioning code byte bit 5: overwrite signaling with signaling trunk conditioning code byte bit 4: replace pcm data with digital miliwat pat Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 115 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface bit 3: selects A-law mW patter instead of U-law bit 2: invert most significant bit of data bit 1,0: unused trnkData sigData : trunk conditioning data byte : signaling data byte bit 7,6,5,4: unused bit 3,2,1,0: A,B,C,D bits : array of control byte : trunk conditioning data byte : signaling data byte Outputs pctlByte trnkData sigData Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Transmit Trunk Conditioning: cometqTxTrnkCfg This function enables or disables trunk conditioning into the transmit stream for all timeslots. PCM data is overwritten by the contents of the TPSC idle code bytes and signaling data is overwritten by the `ABCD' values in the TPSC signaling control registers. Prototype Inputs INT4 cometqTxTrnkCfg (sCMQ_HNDL deviceHandle, UINT2 chan, UINT2 enable) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 enable COMET: not used : enable or disable transmit trunk conditioning Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 116 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Receive Trunk Conditioning: cometqRxTrnkCfg This function allows the user to enable or disable trunk conditioning onto the backplane, overwriting the received data stream. Upon enable, PCM data is overwritten by the contents of the data trunk conditioning registers in the RPSC and signaling data is overwritten by the contents of the signaling trunk conditioning registers in the RPSC. Prototype Inputs INT4 cometqRxTrnkCfg (sCMQ_HNDL deviceHandle, UINT2 chan, UINT2 enable) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 enable COMET: not used : enable or disable receive trunk conditioning Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Pattern receive and generation control: cometqPRGDCtlCfg This function allows the user to configure the pattern generator and detector to insert or detect framed and unframed patterns in both the transmit and receive streams. Prototype INT4 cometqPRGDCtlCfg(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_PRGD_PAT_LEN genLen, eCMQ_PRGD_PAT_LEN detLen, UINT2 unFrmGen, UINT2 unFrmDet, UINT2 rxPatGenLoc) deviceHandle : device Handle (from cometqAdd) chan : E1/T1channels: COMET-QUAD: 0, 1, 2, or 3 genLen Inputs COMET: not used : select 7 or 8 bit pattern insertion: CMQ_PRGD_PAT_8_BIT, CMQ_PRGD_PAT_7_BIT detLen : select 7 or 8 bit pattern detection: CMQ_PRGD_PAT_8_BIT, CMQ_PRGD_PAT_7_BIT unFrmGen unFrmDet rxPatGenLoc : generate unframed pattern if set : detect unframed pattern if set : location of the PRBS generator/detector. If set, the pattern detector is inserted into the transmit path and the generator is inserted into the receive path. If clear, the generator is inserted in the transmit path and the detector is inserted in the receive path. 117 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Pattern receive and generation control: cometqPRGDPatCfg This API provides configuration of the pattern type that the pseudo-random generator/detector uses. The user can specify the pattern type and select between a pseudo-random or a quasirandom sequence. The available patterns for the COMET and COMET-QUAD and the corresponding value to assign to the pat parameter are as follows: Pattern Type COMET-QUAD 220 - 1 215 - 1 211 - 1 COMET 23 - 1 24 - 1 25 - 1 26 - 1 27 - 1 27 - 1, Fractional T1 loopback activate pat enumerated value CMQ_PSEUDO_RANDOM_PAT_2_TO_20 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_15 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_11 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_3R D_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_4t h_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_5t h_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_6t h_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_7t h_MINUS1 CMQ_PSEUDO_RANDOM_PAT_FRAC_T1 _ACTIVATE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 118 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface COMET Pattern Type 29 - 1, O.153 compliant 210 - 1 211 - 1, O.152 compliant 215 - 1, O.151 compliant 217 - 1 218 - 1 220 - 1, O.153 compliant 220 - 1, O.151 compliant, Quasirandom (quasiRand = 1) pat enumerated value CMQ_PSEUDO_RANDOM_PAT_2_TO_9t h_MINUS1_O_153 CMQ_PSEUDO_RANDOM_PAT_2_TO_10 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_11 th_MINUS1_O_152 CMQ_PSEUDO_RANDOM_PAT_2_TO_15 th_MINUS1_O_151 CMQ_PSEUDO_RANDOM_PAT_2_TO_17 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_18 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_20 th_MINUS1_O_153 CMQ_PSEUDO_RANDOM_PAT_2_TO_20 th_MINUS1_O_151 221 - 1 222 - 1 223 - 1, O.151 compliant 225 - 1 228 - 1 229 - 1 CMQ_PSEUDO_RANDOM_PAT_2_TO_21 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_22 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_23 th_MINUS1_O_151 CMQ_PSEUDO_RANDOM_PAT_2_TO_25 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_28 th_MINUS1 CMQ_PSEUDO_RANDOM_PAT_2_TO_29 th_MINUS1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 119 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface COMET Pattern Type All ones All zeroes Alternating 1's and 0's Double alternating 1's and 0's 3 1's in 24 bits one 1 in 16 bits one 1 in 8 bits one 1 in 4 bits Inband Activate loopback pattern Inband Deactivate loopback pattern pat enumerated value CMQ_PSEUDO_RANDOM_PAT_ALL_ONE S CMQ_PSEUDO_RANDOM_PAT_ALL_ZER OS CMQ_PSEUDO_RANDOM_PAT_ALT_ONE S_AND_ZEROS CMQ_PSEUDO_RANDOM_PAT_DOUBLE_ ALT_ONES_AND_ZEROS CMQ_PSEUDO_RANDOM_PAT_3_IN_24 CMQ_PSEUDO_RANDOM_PAT_1_IN_16 CMQ_PSEUDO_RANDOM_PAT_1_IN_8 CMQ_PSEUDO_RANDOM_PAT_1_IN_4 CMQ_PSEUDO_RANDOM_PAT_INBAND_ LOOPBACK_ACTIVATE CMQ_PSEUDO_RANDOM_PAT_INBAND_ LOOPBACK_DEACTIVATE Prototype Inputs INT4 cometqPRGDPatCfg(sCMQ_HNDL deviceHandle, UINT2 chan, UINT1 quasiRand, eCMQ_PSEUDO_RANDOM_PATTERN pat) deviceHandle : device Handle (from cometqAdd) chan : E1/T1channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used quasiRand pat : Select quasi-random data instead of pseudo-random. : Pattern type as appropriate for COMET-QUAD or COMET Outputs Returns Valid States None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 120 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Side Effects None Pattern receive and generation control: cometqPRGDErrInsCfg This function allows the user to configure the data generator and detector error insertion rate for a COMET device. Prototype Inputs INT4 cometqPRGDErrInsCfg(sCMQ_HNDL deviceHandle, eCMQ_ERROR_RATE errRate) deviceHandle : device Handle (from cometqAdd) errRate : Selects the error insertion probability: CMQ_ERROR_RATE_OFF, CMQ_ERROR_RATE_SINGLE, CMQ_ERROR_RATE_10_TO_MINUS1, CMQ_ERROR_RATE_10_TO_MINUS2, CMQ_ERROR_RATE_10_TO_MINUS3, CMQ_ERROR_RATE_10_TO_MINUS4, CMQ_ERROR_RATE_10_TO_MINUS5, CMQ_ERROR_RATE_10_TO_MINUS6, CMQ_ERROR_RATE_10_TO_MINUS7 Outputs Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None 4.10 Interrupt Service Functions This section describes interrupt-service functions that perform the following tasks: * * * Set, get and clear the interrupt enable mask Read and process the interrupt-status registers Poll and process the interrupt-status registers See page 25 for an explanation of our interrupt servicing architecture. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 121 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Configuring ISR Processing: cometqISRConfig Allows the USER to configure how ISR processing is to be handled: polling (CMQ_POLL_MODE) or interrupt driven (CMQ_ISR_MODE). If polling is selected, the USER is responsible for calling cometqPoll to collect interrupt data from the device. ISR configuration is the same for both COMET and COMET-QUAD devices. Prototype Inputs INT4 cometqISRConfig(sCMQ_HNDL deviceHandle, eCMQ_ISR_MODE mode) deviceHandle : device Handle (from cometqAdd) mode : mode of operation : CMQ_ISR_MODE or CMQ_POLL_MODE Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Getting the Interrupt Status Mask: cometqGetMask Returns the interrupt mask currently stored within the DDB. For COMET devices, all mask structure arrays within pmask except for the HDLC interrupt mask arrays use only one element as there is only one framer present on the device. There are three HDLC controllers on the COMET and the corresponding mask arrays, rdlcEn and tdpr, contain their interrupt masks as the first three elements of the array. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqGetMask(sCMQ_HNDL deviceHandle, sCMQ_ISR_MASK *pmask) deviceHandle : device Handle (from cometqAdd) pmask : (pointer to) mask structure pmask : (pointer to) updated mask structure Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 122 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Setting the Interrupt Enable Mask: cometqSetMask Sets individual interrupt bits and registers in the COMET or COMET-QUAD device. Any bits that are set in the passed structure are set in the associated COMET or COMET-QUAD registers. All other interrupt bits are left unmodified. For COMET devices, all mask structure arrays within pmask except for the HDLC interrupt mask arrays use only one element as there is only one framer present on the device. There are three HDLC controllers on the COMET and the corresponding mask arrays, rdlcEn and tdpr, contain their interrupt masks as the first three elements of the array. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqSetMask(sCMQ_HNDL deviceHandle, sCMQ_ISR_MASK *pmask) deviceHandle : device Handle (from cometqAdd) pmask : (pointer to) mask structure None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE May change the operation of the ISR / DPR Clearing the Interrupt Enable Mask: cometqClearMask Clears individual interrupt bits and registers in the COMET or COMET-QUAD device. Any bits that are set in the passed structure are cleared in the associated COMET or COMET-QUAD registers. All other interrupt bits are left unmodified. For COMET devices, all mask structure arrays within pmask except for the HDLC interrupt mask arrays use only one element as there is only one framer present on the device. There are three HDLC controllers on the COMET and the corresponding mask arrays, rdlcEn and tdpr, contain their interrupt masks as the first three elements of the array. Prototype Inputs Outputs Returns Valid States INT4 cometqClearMask(sCMQ_HNDL deviceHandle, sCMQ_ISR_MASK *pmask) deviceHandle : device Handle (from cometqAdd) pmask : (pointer to) mask structure None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 123 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Side Effects May change the operation of the ISR / DPR Polling the Interrupt Status Registers: cometqPoll Commands the driver to poll the interrupt registers in the device. The call will fail unless the device was initialized (via cometqInit) or configured (via cometqISRConfig) into polling mode. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqPoll(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE None Interrupt Service Routine: cometqISR Reads the state of the interrupt registers in the COMET or COMET-QUAD and stores them in an ISV. Performs whatever functions are needed to clear the interrupt, from simply clearing bits to complex functions. This routine is called by the application code from within sysCometqISRHandler. If ISR mode is configured, all interrupts that were detected are disabled and the ISV is returned to the Application. Note that the Application is then responsible for sending this buffer to the DPR task. If polling mode is selected, no ISV is returned to the Application and the DPR is called directly with the ISV. Prototype Inputs Outputs Returns Valid States Side Effects Pseudocode void* cometqISR(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None (pointer to) ISV buffer (to send to the DPR) or NULL (pointer) CMQ_ACTIVE None Begin get an ISV buffer update ISV with current interrupt status if no valid interrupt condition return NULL Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 124 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface if in ISR mode disable all detected interrupts return ISV else (Polling mode) call cometqDPR output NULL End Deferred Processing Routine: cometqDPR Acts on data contained in the passed ISV, allocates one or more DPV buffers (via sysCometqDPVBufferGet) and invokes one or more callbacks (if defined and enabled). This routine is called by the application code, within sysCometqDPRTask. Note that the callbacks are responsible for releasing the passed DPV. It is recommended that this be done as soon as possible to avoid running out of DPV buffers. This function operates the same for both COMET and COMET-QUAD devices. Prototype Inputs Outputs Returns Valid States Side Effects Pseudocode void cometqDPR(sCMQ_ISV* pisv) pisv : (pointer to) ISV buffer None None CMQ_ACTIVE None Begin for each ISV element (section) get and fill out a DPV buffer if callback (from cometqInit) is not NULL invoke (section) callback release ISV by calling sysCometqISVBufferRtn End Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 125 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface 4.11 Status and Statistics Functions This section provides access to the on-chip statistics and counts interface. It also provides an interface to control the transmission of automatic performance reports in the transmit stream when in T1 ESF mode. The user can enable, disable, and force a manual update of the performance report as well as read the performance report to examine its contents. Performance monitoring statistics: cometqForceStatsUpdate This function forces the performance monitor counters obtained by calling cometqGetStats to be updated from the internal holding registers. This function must be called before cometqGetStats is invoked. For COMET-QUAD devices, registers for all four quadrants are updated. When the values have been loaded from the internal holding registers, an interrupt will be generated if the performance monitoring transfer indication interrupt is enabled. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqForceStatsUpdate(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Performance monitoring statistics: cometqGetStats This function retrieves framing statistics from the hardware T1/E1 performance monitoring registers. When calling this function, it is assumed that the user forced the registers to update by calling cometqForceStatsUpdate. For COMET devices, the arrays within pData use only the first element of the four element arrays as there is only one framer present on the device. Prototype Inputs Outputs Returns INT4 cometqGetStats(sCMQ_HNDL deviceHandle, sCMQ_FRM_CNTS *pData) deviceHandle : device Handle (from cometqAdd) pData : framer statistics structure Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 126 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States Side Effects CMQ_ACTIVE, CMQ_INACTIVE None Framer status: cometqGetStatus This function retrieves status and alarms information for either the T1 or E1 framers as appropriate based on the current operating mode. Loss of signal, loss of frame, AIS and yellow alarm status information is available for T1 and E1. For E1, loss of CRC-4 multiframe, loss of signaling multiframe, and timeslot 16 RAI indication is also available. For COMET devices, the arrays within pStatus use only the first element of the four element arrays as there is only one framer present on the device. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqGetStatus(sCMQ_HNDL deviceHandle, sCMQ_FRM_STATUS *pStatus) deviceHandle : device Handle (from cometqAdd) pStatus : framer status structure Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Status of line clocks: cometqLineClkStatGet This function provides the clock inputs status as well as the synchronization status of the clock service unit. Prototype Inputs INT4 cometqLineClkStatGet(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_CLK_STATUS *pclkStat) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs Returns Valid States Side Effects pclkStat : clock status structure Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 127 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Pattern receive and generation control: cometqPRGDCntGet This function retrieves the bit error count that is maintained in the pseudo-random generator/detector within the device. Prototype Inputs INT4 cometqPRGDCntGet(sCMQ_HNDL deviceHandle, UINT2 chan, UINT4 *pcount) deviceHandle : device Handle (from cometqAdd) chan : E1/T1channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs Returns Valid States Side Effects pcount : total bit error count Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Pattern receive and generation control: cometqPRGDGetBitCnt This function provides the user with the bit count maintained in the PRBS within a COMET device. This function is supported by the COMET only. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqPRGDGetBitCnt(sCMQ_HNDL deviceHandle, UINT4 *pcount) deviceHandle : device Handle (from cometqAdd) pcount : current bit count Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Automatic performance report generation: cometqPmonSet Enable/Disable one second update of Auto Performance Report Monitoring (APRM). This function is valid only in T1 ESF framing mode. For COMET devices, the user can force a manual insertion of a performance report into the transmit stream when automatic transmission is disabled. Prototype INT4 cometqPmonSet(sCMQ_HNDL deviceHandle, UINT2 chan, eCMQ_APRM_ACTION action) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 128 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Inputs deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 action COMET: not used : specifies the action to perform: CMQ_AUTO_PMON_UPDATE_DISABLE, CMQ_AUTO_PMON_UPDATE_ENABLE, CMQ_AUTO_PMON_UPDATE_MAN (COMET only - forces manual update) Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE CMQ_INACTIVE None Automatic performance report generation: cometqPmonReportGet This API returns the current one second performance report. This function is valid only in T1 ESF framing mode. Prototype Inputs INT4 cometqPmonReportGet(sCMQ_HNDL deviceHandle, UINT2 chan, sCMQ_STAT_APRM *pPmonReport) deviceHandle : device Handle (from cometqAdd) chan : E1/T1 channel: COMET-QUAD: 0, 1, 2, or 3 COMET: not used Outputs Returns Valid States Side Effects : performance report structure pPmonReport Success = CMQ_SUCCESS Failure = CMQ_ACTIVE CMQ_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 129 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface 4.12 Device Diagnostics Register access test: cometqTestReg This function verifies hardware register integrity by writing and reading back values. The register test operates on both COMET or COMET-QUAD devices. Prototype Inputs Outputs Returns Valid States Side Effects INT4 cometqTestReg(sCMQ_HNDL deviceHandle) deviceHandle : device Handle (from cometqAdd) None Success = CMQ_SUCCESS Failure = CMQ_PRESENT None Framer loopback: cometqLoopFramer Clears / Sets a loopback of type line, payload, or digital within the E1/T1 framer section of the device. Note that when performing a line loopback, the transmit jitter attenuators reference and output clock divisors are set to 0x2F, the transmit timing options register is modified to jitter attenuated loop timing, and the transmit elastic store is enabled. Prototype Inputs INT4 cometqLoopFramer(sCMQ_HNDL deviceHandle, UINT2 framer, eCMQ_LOOPBACK_TYPE type) deviceHandle : device Handle (from cometqAdd) framer : framer number: COMET-QUAD: 0, 1, 2, or 3 COMET: not used type : loopback type: CMQ_LOOPBACK_NONE (disable), CMQ_LOOPBACK_DIGITAL, CMQ_LOOPBACK_LINE, or CMQ_LOOPBACK_PAYLOAD Outputs Returns None Success = CMQ_SUCCESS Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 130 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Valid States Side Effects CMQ_ACTIVE, CMQ_INACTIVE TJAT reference and output clock divisors, transmit timing options modified if line loopback specified DS0 loopback: cometqLoopTslots This function enables or disables DS0 loopback on specified DS0s. To facilitate DS0 loopback, the receive elastic store must be bypassed. As such, the current receive backplane configuration must be clock master otherwise DS0 loopback is not possible. Prototype Inputs INT4 cometqLoopTslots(sCMQ_HNDL deviceHandle, UINT2 framer, UINT4 timeSlot, UINT2 enable) deviceHandle : device Handle (from cometqAdd) framer timeSlot COMET-QUAD: 0, 1, 2, or 3 COMET: not used : bit mask for timeslots to loopback T1: bit 0-23 : channels 1-24 bit 24-31 : unused E1: bit 0-31 : timeslots 0-31 : sets loop if non-zero, else clears loop : framer number: enable Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Analog transmitter bypass: cometqTxAnalogByp This function enables or disables bypass of the TXRING and TXTIP outputs to use the digital TDAT and TCLKO lines. This function is for COMET devices only. Prototype Inputs INT4 cometqTxAnalogByp(sCMQ_HNDL deviceHandle, UINT1 enable) deviceHandle : device Handle (from cometqAdd) enable : enable/disable analog bypass Outputs None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 131 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Returns Valid States Side Effects Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None Analog transmitter bypass: cometqRxAnalogByp This function enables or disables bypass of the RXRING and RXTIP outputs to use the digital RDAT and RCLK lines. This function is for COMET devices only. Prototype Inputs INT4 cometqRxAnalogByp(sCMQ_HNDL deviceHandle, UINT1 enable) deviceHandle : device Handle (from cometqAdd) enable : enable/disable analog bypass Outputs Returns Valid States Side Effects None Success = CMQ_SUCCESS Failure = CMQ_ACTIVE, CMQ_INACTIVE None 4.13 Callback Functions The COMET-QUAD driver has the capability to callback to functions within the USER code when certain events occur. These events and their associated callback routine declarations are detailed below. There is no USER code action that is required by the driver for these callbacks - the USER is free to implement these callbacks in any manner or else they can be deleted from the driver. The names given to the callback functions are given as examples only. The addresses of the callback functions invoked by the cometqDPR function are passed during the cometqInit call (inside a DIV). However the USER shall use the exact same prototype. The Application is left responsible for releasing the passed DPV as soon as possible (to avoid running out of DPV buffers) by calling sysCometqDPVBufferRtn either within the callback function or later inside the Application code. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 132 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Calling Back to the Application due to Interface events: cometqCbackIntf This callback function is provided by the USER and is used by the DPR to report significant Interface section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the cometqInit call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cometqCbackIntf (sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) usrCtxt pdpv : user context (from cometqAdd) : (pointer to) DPV that describes this event None None CMQ_ACTIVE None Calling Back to the Application due to T1 / E1 Framer events: cometqCbackFramer This callback function is provided by the USER and is used by the DPR to report significant Framer section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the cometqInit call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cometqCbackFramer (sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) usrCtxt pdpv : user context (from cometqAdd) : (pointer to) DPV that describes this event None None CMQ_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 133 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Calling Back to the Application due to Signal Insertion / Extraction events: cometqCbackSigInsExt This callback function is provided by the USER and is used by the DPR to report significant Signal Insertion/Extraction section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the cometqInit call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cometqCbackSigInsExt (sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) usrCtxt pdpv : user context (from cometqAdd) : (pointer to) DPV that describes this event None None CMQ_ACTIVE None Calling Back to the Application due to Performance Monitoring events: cometqCbackPMon This callback function is provided by the USER and is used by the DPR to report significant Performance Monitoring section events back to the application. This function should be nonblocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the cometqInit call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cometqCbackPMon (sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) usrCtxt pdpv : user context (from cometqAdd) : (pointer to) DPV that describes this event None None CMQ_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 134 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Application Programming Interface Calling Back to the Application due to Alarm Inband Communications events: cometqCbackAlarmInBand This callback function is provided by the USER and is used by the DPR to report significant Alarm Inband Communications section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the cometqInit call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cometqCbackAlarmInBand (sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) usrCtxt pdpv : user context (from cometqAdd) : (pointer to) DPV that describes this event None None CMQ_ACTIVE None Calling Back to the Application due to Serial Controller events: cometqCbackSerialCtl This callback function is provided by the USER and is used by the DPR to report significant Serial Controller section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the cometqInit call. If the address of the callback function was passed as a NULL at initialization no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cometqCbackSerialCtl (sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) usrCtxt pdpv : user context (from cometqAdd) : (pointer to) DPV that describes this event None None CMQ_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 135 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Hardware Interface 5 HARDWARE INTERFACE The COMET-QUAD driver interfaces directly with the USER's hardware. In this section of the manual, a listing of each point of interface is shown, along with a declaration and any specific porting instructions. It is the responsibility of the USER to connect these requirements into the hardware, either by defining a macro or by writing a function for each item listed. Care should be taken when matching parameters and return values. The hardware interface API is device independent and is thus the same for both COMET and COMET-QUAD devices. 5.1 Device I/O Reading from a Device Register: sysCometqRead The most basic hardware connection - reads the contents of a specific register location. This macro should be UINT1 oriented and should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function. Format Prototype Inputs Outputs Returns #define sysCometqRead(addr) UINT1 sysCometqRead(UINT1 *addr) addr : register location to be read None value read from the addressed register location Writing to a Device Register: sysCometqWrite The most basic hardware connection - writes the supplied value to the specific register location. This macro should be UINT1 oriented and should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function. Format Prototype Inputs Outputs Returns #define sysCometqWrite(addr, value) UINT1 sysCometqWrite(UINT1 *addr, UINT1 value) addr value : register location to be written : data to be written None Value written to the addressed register location Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 136 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Hardware Interface 5.2 System-Specific Interrupt Servicing The porting of an ISR routine between platforms is a rather difficult task. There are many different implementations of these hardware level routines. In this driver, the USER is responsible for installing an interrupt handler (sysCometqISRHandler) in the interrupt vector table of the system processor. This handler shall call cometqISR for each device that has interrupt servicing enabled, to perform the ISR related housekeeping required by each device. During execution of the API function cometqModuleStart / cometqModuleStop the driver informs the application that it is time to install / uninstall this shell via sysCometqISRHandlerInstall / sysCometqISRHandlerRemove. Note: A device can be initialized with ISR disabled. In that mode, the USER should periodically invoke a provided `polling' routine (cometqPoll) that in turn calls cometqISR. Installing the ISR Handler: sysCometqISRHandlerInstall Installs the USER-supplied Interrupt Service Routine (ISR), sysCometqISRHandler, into the processor's interrupt vector table. Format Prototype Inputs Outputs Returns Pseudocode #define sysCometqISRHandlerInstall(func) INT4 sysCometqISRHandlerInstall(void *func) func : (pointer to) the function sysCometqISRHandler None Success = 0 Failure = ISR Handler: sysCometqISRHandler This routine is invoked when one or more COMET or COMET-QUAD devices raise the interrupt line to the microprocessor. This routine invokes the driver-provided routine, cometqISR, for each device registered with the driver. Format Prototype Inputs #define sysCometqISRHandler() void sysCometqISRHandler(void) None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 137 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Hardware Interface Outputs Returns Pseudocode None None Begin for each device registered with the driver call cometqISR if returned ISV buffer is not NULL send ISV buffer to the DPR End Removing the ISR Handler: sysCometqISRHandlerRemove Disables interrupt processing for all COMET or COMET-QUAD device. Removes the USERsupplied Interrupt Service routine (ISR), sysCometqISRHandler, from the processor's interrupt vector table. Format Prototype Inputs Outputs Returns Pseudocode #define sysCometqISRHandlerRemove() void sysCometqISRHandlerRemove(void) None None None Begin remove sysCometqISRHandler from the processor's interrupt vector table End Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 138 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface 6 RTOS INTERFACE The COMET-QUAD driver requires the use of some RTOS resources. In this section of the manual, a listing of each required resource is shown, along with a declaration and any specific porting instructions. Note that it is the responsibility of the USER to connect these requirements into the RTOS, either by defining a macro or by writing a function for each item listed. Care should be taken when matching parameters and return values. The RTOS interface API is device independent and is thus the same for both COMET and COMET-QUAD devices. 6.1 Memory Allocation / De-Allocation Allocating Memory: sysCometqMemAlloc Allocates specified number of bytes of memory. Format Prototype Inputs Outputs Returns #define sysCometqMemAlloc(numBytes) UINT1* sysCometqMemAlloc(UINT4 numBytes) numBytes : number of bytes to be allocated None Success = Pointer to first byte of allocated memory Failure = NULL pointer (memory allocation failed) Freeing Memory: sysCometqMemFree Frees memory that was allocated using sysCometqMemAlloc. Format Prototype Inputs Outputs Returns #define sysCometqMemFree(pfirstByte) void sysCometqMemFree(UINT1* pfirstByte) pfirstByte : pointer to first byte of the memory region being de-allocated None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 139 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface Setting memory: sysCometqMemSet Sets a specified contiguous block of memory to the given value. Format Prototype Inputs #define sysCometqMemSet(pmem, val, sz) void sysCometqMemSet(UINT1* pmem, UINT1 val, size_t sz) pmem val sz : pointer to first byte of memory to set : value to set the memory to : number of bytes to set to val starting at pmem Outputs Returns None None Copying memory: sysCometqMemCpy Copies a given number of bytes from one memory location to another. Format Prototype Inputs #define sysCometqMemCpy(pdst, psrc, sz) void sysCometqMemCpy(UINT1* pdst, UINT1* psrc, size_t sz) pdst psrc sz : pointer to the destination : pointer to the source : number of bytes to copy from the source to the destination Outputs Returns None None 6.2 Buffer Management All operating systems provide some sort of buffer system, particularly for use in sending and receiving messages. The following calls, provided by the USER, allow the Driver to Get and Return buffers from the RTOS. It is the USER's responsibility to create any special resources or pools to handle buffers of these sizes during the sysCometqBufferStart call. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 140 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface Starting Buffer Management: sysCometqBufferStart Alerts the RTOS that the time has come to make sure ISV buffers and DPV buffers are available and sized correctly. This may involve the creation of new buffer pools and it may involve nothing, depending on the RTOS. Format Prototype Inputs Outputs Returns #define sysCometqBufferStart() INT4 sysCometqBufferStart(void) None None Success = 0 Failure = Getting an ISV Buffer: sysCometqISVBufferGet Gets a buffer from the RTOS that will be used by the ISR code to create an Interrupt Service Vector (ISV). The ISV consists of data transferred from the devices interrupt status registers. Format Prototype Inputs Outputs Returns #define sysCometqISVBufferGet() sCMQ_ISV* sysCometqISVBufferGet(void) None None Success = (pointer to) a ISV buffer Failure = NULL (pointer) Returning an ISV Buffer: sysCometqISVBufferRtn Returns an ISV buffer to the RTOS when the information in the block is no longer needed by the DPR. Format Prototype Inputs Outputs Returns #define sysCometqISVBufferRtn(pISV) void sysCometqISVBufferRtn(sCMQ_ISV* pisv) pisv : (pointer to) a ISV buffer None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 141 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface Getting a DPV Buffer: sysCometqDPVBufferGet Gets a buffer from the RTOS that will be used by the DPR code to create a Deferred Processing Vector (DPV). The DPV consists of information about the state of the device that is to be passed to the USER via a callback function. Format Prototype Inputs Outputs Returns #define sysCometqDPVBufferGet() sCMQ_DPV *sysCometqDPVBufferGet(void) None None Success = (pointer to) a DPV buffer Failure = NULL (pointer) Returning a DPV Buffer: sysCometqDPVBufferRtn Returns a DPV buffer to the RTOS when the information in the block is no longer needed by the DPR. Format Prototype Inputs Outputs Returns #define sysCometqDPVBufferRtn(pDPV) void sysCometqDPVBufferRtn(sCMQ_DPV *pdpv) pdpv : (pointer to) a DPV buffer None None Stopping Buffer Management: sysCometqBufferStop Alerts the RTOS that the Driver no longer needs any of the ISV buffers or DPV buffers and that if any special resources were created to handle these buffers, they can be deleted now. Format Prototype Inputs Outputs Returns #define sysCometqBufferStop() void sysCometqBufferStop(void) None None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 142 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface 6.3 Timers Sleeping a Task: sysCometqTimerSleep Suspends execution of a driver task for a specified number of milliseconds. Format Prototype Inputs Outputs Returns #define sysCometqTimerSleep(time) void sysCometqTimerSleep(UINT4 time) time : sleep time in milliseconds None Success = 0 Failure = 6.4 Preemption Disabling Preemption: sysCometqPreemptDis This routine prevents the calling task from being preempted by both other tasks and any interrupt requests. Format Prototype Inputs Outputs Returns #define sysCometqPreemptDis() INT4 sysCometqPreemptDis(void) None None Preemption key (passed back as an argument in sysCometqPreemptEn) Re-Enabling Preemption: sysCometqPreemptEn This routine allows the calling task to be preempted, granting access to both other tasks and interrupt processing. Format Prototype Inputs #define sysCometqPreemptEn(key) void sysCometqPreemptEn(INT4 key) key : preemption key (returned by Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 143 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface sysCometqPreemptDis) Outputs Returns None None 6.5 System-Specific DPR Routine The porting of a task between platforms is not always simple. There are many different implementations of the RTOS level parameters. In this driver, the USER is responsible for creating a `shell' (sysCometqDPRTask) that in turn calls cometqDPR with an ISV to perform the ISR related processing that is required by each interrupting device. During execution of the API functions cometqModuleStart and cometqModuleStop, the driver informs the application that it is time to install and uninstall this shell via the functions sysCometqDPRTaskInstall and sysCometqDPRTaskRemove, that needs to be supplied by the USER. Installing the DPR Task: sysCometqDPRTaskInstall Installs the DPR task as the function sysCometqDPRTask. Format Prototype Inputs Outputs Returns Pseudocode #define sysCometqDPRTaskInstall(func) INT4 sysCometqDPRTaskInstall(void *func) func : (pointer to) the function cometqDPR None Success = 0 Failure = DPR Task: sysCometqDPRTask This routine is installed as a separate task within the RTOS. It waits for messages from the cometqISR that provide interrupt event notification and then invokes cometqDPR for the appropriate device. Format Prototype #define sysCometqDPRTask() void sysCometqDPRTask(void) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 144 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual RTOS Interface Inputs Outputs Returns Pseudocode None None None Begin do wait for an ISV buffer (sent by cometqISR) call cometqDPR with that ISV loop forever End Removing the DPR Task: sysCometqDPRTaskRemove Informs the application that it is time to remove (suspend) the USER supplied task sysCometqDPRTask. Format Prototype Inputs Outputs Returns Pseudocode #define sysCometqDPRTaskRemove() void sysCometqDPRTaskRemove(void) None None None Begin remove/suspend sysCometqDPRTask End Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 145 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Porting the COMET-QUAD Driver 7 PORTING THE COMET-QUAD DRIVER This section of the manual outlines how to port the COMET and COMET-QUAD device driver to your hardware and RTOS platform. However, this manual can offer only guidelines for porting the COMET and COMET-QUAD driver as each platform and application is unique. 7.1 Driver Source Files The C source files listed in the following table contain the code for the COMET and COMETQUAD driver. You may need to modify the existing code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and header files (inc). The src files contain the functions and the inc files contain the constants and macros. Directory src File cmq_api.c cmq_diag.c cmq_hw.c cmq_isr.c cmq_rtos.c cmq_stats.c cmq_util.c cmq_frm.c cmq_sig.c cmq_ser.c cmq_inbd.c cmq_intf.c Description Device and module management Diagnostics functions Hardware specific functions ISR processing functions RTOS specific functions Status and statistics functions Miscellaneous functions Framer configuration functions Signaling interface Serial control functions Alarms and inband communications Interface configuration functions Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 146 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Porting the COMET-QUAD Driver inc cmq_api.h cmq_defs.h API function prototypes Constants, macros and enumerated types Driver error codes Non-API function prototypes Hardware specific constants, macros and function prototypes RTOS specific constants, macros and function prototypes Driver structures Standard types cmq_err.h cmq_fns.h cmq_hw.h cmq_rtos.h cmq_strs.h cmq_typs.h 7.2 Driver Porting Procedures The following procedures summarize how to port the COMET-QUAD driver to your platform. To port the COMET and COMET-QUAD driver to your platform: Step 1: Port the driver's RTOS extensions (page 147) Step 2: Port the driver to your hardware platform (page 148) Step 3: Port the driver's application-specific elements (page 149) Step 4: Build the driver (page 151) Step 1: Porting Driver RTOS Extensions The RTOS extensions encapsulate all RTOS specific services and data types used by the driver. These RTOS extensions include: * * * Memory management Task management Message queues, semaphores and timers The compiler-specific data type definitions are located in cmq_typs.h. The cmq_rtos.h and cmq_rtos.c files contain macros and functions for RTOS specific services. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 147 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Porting the COMET-QUAD Driver To port the driver's RTOS extensions: 1. Modify the data types in cmq_typs.h. The number after the type identifies the data-type size. For example, UINT4 defines a 4-byte (32-bit) unsigned integer. Substitute the compiler types that yield the desired types as defined in this file. 2. Modify the RTOS specific macros in cmq_rtos.h: Service Type Memory Macro Name sysCometqMemAlloc sysCometqMemFree sysCometqMemCpy Description Allocates the memory block Frees the memory block Copies the memory block from src to dest Sets each character in the memory buffer sysCometqMemSet 3. Modify the RTOS specific functions in cmq_rtos.c: Service Type Interrupt Timer Buffer Function Name Description Deferred interrupt-processing routine (DPR) Sleeps a task Start buffer management Gets a ISV buffer Returns a ISV buffer Gets a DPV buffer Returns a DPV buffer Stops buffer management sysCometqDPRTask sysCometqTimerSleep sysCometqBufferStart sysCometqISVBufferGet sysCometqISVBufferRtn sysCometqDPVBufferGet sysCometqDPVBufferRtn sysCometqBufferStop Step 2: Porting Drivers to Hardware Platforms Step 2 describes how to modify the COMET-QUAD driver for your hardware platform. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 148 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Porting the COMET-QUAD Driver To port the driver to your hardware platform: 1. Modify the hardware specific functions in cmq_hw.c: Service Type Interrupt Function Name sysCometqISRHandlerInstall Description Installs the interrupt handler into the processor's interrupt vector table and spawns the DPR task Removes the interrupt handler from the RTOS and deletes the DPR task Interrupt handler for the COMET or COMET-QUAD device Reads from a device register Writes to a device register sysCometqISRHandlerRemove sysCometqISRHandler Device I/O sysCometqRead sysCometqWrite Step 3: Porting Driver Application Specific Elements Application specific elements are configuration constants used by the API for developing an application. This section of the manual describes how to modify the application specific elements in the COMET-QUAD driver. To port the driver's application specific elements: 1. Modify the type definition for the user context in cmq_typs.h. The user context is used to identify a device in your application callbacks. 2. Modify the value of the base error code (CMQ_ERR_BASE) in cmq_err.h. This ensures that the driver error codes do not overlap other error codes used in your application. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 149 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Porting the COMET-QUAD Driver 3. Define the application-specific constants for your hardware configuration in cmq_defs.h: Device Constant CMQ_MAX_DEVS Description The maximum number of COMET or COMET-QUAD devices on each card The maximum number of COMET or COMET-QUAD initialization profiles Default 5 CMQ_MAX_INIT_PROFS 5 4. Define the following application-specific constants for your RTOS-specific services in cometq_rtos.h: Task Constant CMQ_MAX_ISV_BUF Description The maximum number of ISV buffers The maximum number of DPV buffers The maximum number of messages in the message queue Deferred Task (DPR) task priority DPR task stack size, in bytes Default 50 950 250 85 8192 CMQ_MAX_DPV_BUF CMQ_MAX_MSGS CMQ_DPR_TASK_PRIORITY CMQ_DPR_TASK_STACK_SZ 5. Code the callback functions according to your application. There are sample callback functions in cmq_app.c. The driver will call these callback functions when an event occurs on the device. These functions must conform to the following prototype (cback should be replaced with your callback function name): void cback(sCMQ_USR_CTXT usrCtxt, sCMQ_DPV *pdpv) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 150 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Porting the COMET-QUAD Driver Step 4: Building the Driver Step 4 describes how to build the COMET or COMET-QUAD driver. To build the driver: 1. Ensure that the directory variable names in the makefile reflect your actual driver and directory names. 2. Compile the source files and build the COMET or COMET-QUAD driver using your make utility. 3. Link the COMET or COMET-QUAD driver to your application code. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001401, Issue 2 151 COMET (PM4351) and COMET-QUAD (PM4354) Driver Manual Appendix A: Coding Conventions APPENDIX A: CODING CONVENTIONS This section of the manual describes the coding conventions used to implement PMC driver software. Variable Type Definitions Table 50: Variable Type Definitions Type UINT1 UINT2 UINT4 INT1 INT2 INT4 Description unsigned integer - 1 byte unsigned integer - 2 bytes unsigned integer - 4 bytes signed integer - 1 byte signed integer - 2 bytes signed integer - 4 bytes Naming Conventions Table 51 summarizes the naming conventions followed by PMC-Sierra driver software. Detailed descriptions are then provided in the following sub-sections. The names used in the drivers are detailed enough to make their purpose fairly clear. Note that the device name appears in prefix. Table 51: Naming Conventions Type Macros Enumerated Types Constants Naming convention Uppercase, prefix with "m" and device abbreviation Uppercase, prefix with "e" and device abbreviation Uppercase, prefix with device abbreviation Examples mCMQ_REG_ADDR mCMQ_[BLK]_ |
Price & Availability of 2001401
 |
|
|
|
|
All Rights Reserved © IC-ON-LINE 2003 - 2022 |
| [Add Bookmark] [Contact Us] [Link exchange] [Privacy policy] |
|
Mirror Sites : [www.datasheet.hk]
[www.maxim4u.com] [www.ic-on-line.cn]
[www.ic-on-line.com] [www.ic-on-line.net]
[www.alldatasheet.com.cn]
[www.gdcy.com]
[www.gdcy.net] |